CONFIGURE.md

   1 # Configuration
   2
   3 After [installing](INSTALL.md) the OpenStreetMap website, you may need to carry out some configuration steps depending on your development tasks.
   4
   5 ## Table of Contents
   6
   7 1. [Prerequisites](#prerequisites)
   8 2. [Basic Application Configuration](#basic-application-configuration)
   9 3. [Database Population](#database-population)
  10 4. [User Management](#user-management)
  11 5. [OAuth Setup](#oauth-setup)
  12 6. [Development Tools](#development-tools)
  13 7. [Production Deployment](#production-deployment)
  14 8. [Troubleshooting](#troubleshooting)
  15
  16 ## Prerequisites
  17
  18 Before proceeding with configuration, ensure you have:
  19 - Completed the [installation steps](INSTALL.md)
  20 - Successfully started the Rails server
  21 - Verified the website loads at [http://localhost:3000](http://localhost:3000)
  22
  23 ## Basic Application Configuration
  24
  25 ### Application Settings
  26
  27 Many settings are available in `config/settings.yml`. You can customize your installation of `openstreetmap-website` by overriding these values using `config/settings.local.yml`.
  28
  29 ## Database Population
  30
  31 Your installation comes with no geographic data loaded. Before adding any data using one of the editors (iD, JOSM etc), you can optionally prepopulate the database using an OSM extract.
  32
  33 ### Loading Data with Osmosis (Optional)
  34
  35 > [!NOTE]
  36 > This step is entirely optional. You can start using the editors immediately to create new data, or if you prefer to work with existing data, you can import an extract with [Osmosis](https://wiki.openstreetmap.org/wiki/Osmosis) and the [`--write-apidb`](https://wiki.openstreetmap.org/wiki/Osmosis/Detailed_Usage#--write-apidb_.28--wd.29) task.
  37
  38 To import an extract, run:
  39
  40 ```bash
  41 osmosis --read-pbf greater-london-latest.osm.pbf \
  42   --write-apidb host="localhost" database="openstreetmap" \
  43   user="openstreetmap" password="" validateSchemaVersion="no"
  44 ```
  45
  46 > [!IMPORTANT]
  47 > - Loading an apidb database with Osmosis is about **twenty** times slower than loading the equivalent data with osm2pgsql into a rendering database
  48 > - [`--log-progress`](https://wiki.openstreetmap.org/wiki/Osmosis/Detailed_Usage#--log-progress_.28--lp.29) may be desirable for status updates
  49 > - To be able to edit the data you have loaded, you will need to use this [yet-to-be-written script](https://github.com/openstreetmap/openstreetmap-website/issues/282)
  50
  51 ## User Management
  52
  53 After creating a user through the web interface at [http://localhost:3000/user/new](http://localhost:3000/user/new), you may need to perform additional user management tasks.
  54
  55 > [!TIP]
  56 > If you don't want to set up your development box to send emails, you can manually confirm users and grant permissions through the Rails console.
  57
  58 ### Managing Users via Rails Console
  59
  60 1. **Enter the Rails console:**
  61    ```bash
  62    $ bundle exec rails console
  63    ```
  64
  65 2. **Find the user:**
  66    ```ruby
  67    >> user = User.find_by(:display_name => "My New User Name")
  68    => #[ ... ]
  69    ```
  70
  71 3. **Modify the user as desired:**
  72
  73    **Activate/confirm the user:**
  74    ```ruby
  75    >> user.activate!
  76    => true
  77    ```
  78
  79    **Grant moderator role:**
  80    ```ruby
  81    >> user.roles.create(:role => "moderator", :granter_id => user.id)
  82    => #[ ... ]
  83    ```
  84
  85    **Grant administrator role:**
  86    ```ruby
  87    >> user.roles.create(:role => "administrator", :granter_id => user.id)
  88    => #[ ... ]
  89    ```
  90
  91 4. **Exit the Rails console:**
  92    ```ruby
  93    >> quit
  94    ```
  95
  96 ## OAuth Setup
  97
  98 There are two built-in applications which communicate via the API, and therefore need to be registered as OAuth 2 applications. These are:
  99
 100 * **iD** - the web-based editor
 101 * **The website itself** - for the Notes functionality
 102
 103 You need to register these applications with *one* of the users you created. After that iD and Notes functionality becomes available to every user of the website.
 104
 105 ### Automated OAuth Setup (Recommended)
 106
 107 > [!TIP]
 108 > You can register both applications automatically by running the following rake task:
 109 >
 110 > ```bash
 111 > bundle exec rails oauth:register_apps["My New User Name"]
 112 > ```
 113 >
 114 > This task registers the applications with the "My New User Name" user as the owner and saves their keys to `config/settings.local.yml`. When logged in, the owner should be able to see the apps on the OAuth 2 applications page.
 115
 116 Alternatively you can register the applications manually, as described in the next section.
 117
 118 ### Setting up OAuth for iD
 119
 120 1. **Navigate to OAuth applications:**
 121    - Go to "[OAuth 2 applications](http://localhost:3000/oauth2/applications)" on the My settings page
 122
 123 2. **Register new application:**
 124    - Click on "Register new application"
 125    - **Name:** "Local iD"
 126    - **Redirect URIs:** "http://localhost:3000" (unless you have set up alternatives)
 127
 128 3. **Select permissions:**
 129    Check boxes for the following:
 130    - ✅ 'Read user preferences'
 131    - ✅ 'Modify user preferences'
 132    - ✅ 'Modify the map'
 133    - ✅ 'Read private GPS traces'
 134    - ✅ 'Upload GPS traces'
 135    - ✅ 'Modify notes'
 136
 137 4. **Configure the application:**
 138    - Copy the "Client ID" from the next page
 139    - Edit `config/settings.local.yml` in your rails tree
 140    - Add the "id_application" configuration with the "Client ID" as the value
 141    - Restart your rails server
 142
 143 > [!TIP]
 144 > **Example configuration in `settings.local.yml`:**
 145 > ```yaml
 146 > # Default editor
 147 > default_editor: "id"
 148 > # OAuth 2 Client ID for iD
 149 > id_application: "Snv…OA0"
 150 > ```
 151
 152 ### Setting up OAuth for Notes and Changeset Discussions
 153
 154 To allow [Notes](https://wiki.openstreetmap.org/wiki/Notes) and changeset discussions to work:
 155
 156 1. **Register OAuth application for the website:**
 157    - Go to "[OAuth 2 applications](http://localhost:3000/oauth2/applications)" on the My settings page
 158    - Click on "Register new application"
 159    - **Name:** "OpenStreetMap Web Site"
 160    - **Redirect URIs:** "http://localhost:3000"
 161
 162 2. **Select permissions:**
 163    Check boxes for:
 164    - ✅ 'Modify the map'
 165    - ✅ 'Modify notes'
 166
 167 3. **Configure the application:**
 168    - Copy both the "Client Secret" and "Client ID"
 169    - Edit `config/settings.local.yml`
 170    - Add both configurations
 171    - Restart your rails server
 172
 173 > [!TIP]
 174 > **Example configuration in `settings.local.yml`:**
 175 > ```yaml
 176 > # OAuth 2 Client ID for the web site
 177 > oauth_application: "SGm8QJ6tmoPXEaUPIZzLUmm1iujltYZVWCp9hvGsqXg"
 178 > # OAuth 2 Client Secret for the web site
 179 > oauth_key: "eRHPm4GtEnw9ovB1Iw7EcCLGtUb66bXbAAspv3aJxlI"
 180 > ```
 181
 182 ## Development Tools
 183
 184 ### Viewing Rails Logs
 185
 186 Rails has its own log. To inspect the log during development:
 187
 188 ```bash
 189 tail -f log/development.log
 190 ```
 191
 192 ### Maintaining Your Installation
 193
 194 > [!TIP]
 195 > If your installation stops working for some reason:
 196 >
 197 > - **Update gems:** Sometimes the bundle has been updated. Go to your `openstreetmap-website` directory and run:
 198 >   ```bash
 199 >   bundle install
 200 >   ```
 201 >
 202 > - **Update Node.js modules:** If Node.js modules have been updated, run:
 203 >   ```bash
 204 >   bundle exec bin/yarn install
 205 >   ```
 206 >
 207 > - **Run database migrations:** The OSM database schema is changed periodically. To keep up with improvements:
 208 >   ```bash
 209 >   bundle exec rails db:migrate
 210 >   ```
 211
 212 ## Production Deployment
 213
 214 If you want to deploy `openstreetmap-website` for production use, you'll need to make several changes:
 215
 216 ### Web Server Configuration
 217
 218 > [!WARNING]
 219 > Don't use `rails server` in production. Our recommended approach is to use [Phusion Passenger](https://www.phusionpassenger.com/).
 220
 221 - Instructions are available for [setting it up with most web servers](https://www.phusionpassenger.com/documentation_and_support#documentation)
 222 - Passenger will, by design, use the Production environment and therefore the production database - make sure it contains the appropriate data and user accounts
 223
 224 ### Performance Optimizations
 225
 226 > [!TIP]
 227 > **Consider using CGIMap:** The included version of the map call is quite slow and eats a lot of memory. You should consider using [CGIMap](https://github.com/zerebubuth/openstreetmap-cgimap) instead.
 228
 229 ### Asset Compilation
 230
 231 - **Generate i18n files and precompile assets:**
 232   ```bash
 233   RAILS_ENV=production bundle exec i18n export
 234   bundle exec rails assets:precompile
 235   ```
 236
 237 ### File Permissions
 238
 239 > [!IMPORTANT]
 240 > Make sure the web server user as well as the rails user can read, write and create directories in `tmp/`.
 241
 242 ### Testing on the OSM Dev Server
 243
 244 For example, after developing a patch for `openstreetmap-website`, you might want to demonstrate it to others or ask for comments and testing. To do this you can [set up an instance of openstreetmap-website on the dev server in your user directory](https://wiki.openstreetmap.org/wiki/Using_the_dev_server#Rails_Applications).
 245
 246 ## Troubleshooting
 247
 248 If you have problems with your configuration:
 249
 250 - **Check the Rails log:** Use `tail -f log/development.log` to see what's happening
 251 - **Verify database connectivity:** Ensure PostgreSQL is running and accessible
 252 - **Check file permissions:** Make sure the Rails application can read/write necessary files
 253 - **Review OAuth settings:** Ensure Client IDs and secrets are correctly configured
 254
 255 ### Getting Help
 256
 257 If you need additional assistance:
 258 - **Mailing list:** Ask on the [rails-dev@openstreetmap.org mailing list](https://lists.openstreetmap.org/listinfo/rails-dev)
 259 - **IRC:** Join the [#osm-dev IRC Channel](https://wiki.openstreetmap.org/wiki/IRC)
 260
 261 ## Contributing
 262
 263 For information on contributing changes to the code, see [CONTRIBUTING.md](CONTRIBUTING.md)