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 ### Automated OAuth Setup (Recommended)
 104
 105 > [!TIP]
 106 > You can register both applications automatically by running the following rake task:
 107 >
 108 > ```bash
 109 > bundle exec rails oauth:register_apps["My New User Name"]
 110 > ```
 111 >
 112 > 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.
 113
 114 Alternatively you can register the applications manually, as described in the next section.
 115
 116 ### Setting up OAuth for iD
 117
 118 1. **Navigate to OAuth applications:**
 119    - Go to "[OAuth 2 applications](http://localhost:3000/oauth2/applications)" on the My settings page
 120
 121 2. **Register new application:**
 122    - Click on "Register new application"
 123    - **Name:** "Local iD"
 124    - **Redirect URIs:** "http://localhost:3000" (unless you have set up alternatives)
 125
 126 3. **Select permissions:**
 127    Check boxes for the following:
 128    - ✅ 'Read user preferences'
 129    - ✅ 'Modify user preferences'
 130    - ✅ 'Modify the map'
 131    - ✅ 'Read private GPS traces'
 132    - ✅ 'Upload GPS traces'
 133    - ✅ 'Modify notes'
 134
 135 4. **Configure the application:**
 136    - Copy the "Client ID" from the next page
 137    - Edit `config/settings.local.yml` in your rails tree
 138    - Add the "id_application" configuration with the "Client ID" as the value
 139    - Restart your rails server
 140
 141 > [!TIP]
 142 > **Example configuration in `settings.local.yml`:**
 143 > ```yaml
 144 > # Default editor
 145 > default_editor: "id"
 146 > # OAuth 2 Client ID for iD
 147 > id_application: "Snv…OA0"
 148 > ```
 149
 150 ### Setting up OAuth for Notes and Changeset Discussions
 151
 152 To allow [Notes](https://wiki.openstreetmap.org/wiki/Notes) and changeset discussions to work:
 153
 154 1. **Register OAuth application for the website:**
 155    - Go to "[OAuth 2 applications](http://localhost:3000/oauth2/applications)" on the My settings page
 156    - Click on "Register new application"
 157    - **Name:** "OpenStreetMap Web Site"
 158    - **Redirect URIs:** "http://localhost:3000"
 159
 160 2. **Select permissions:**
 161    Check boxes for:
 162    - ✅ 'Modify the map'
 163    - ✅ 'Modify notes'
 164
 165 3. **Configure the application:**
 166    - Copy both the "Client Secret" and "Client ID"
 167    - Edit `config/settings.local.yml`
 168    - Add both configurations
 169    - Restart your rails server
 170
 171 > [!TIP]
 172 > **Example configuration in `settings.local.yml`:**
 173 > ```yaml
 174 > # OAuth 2 Client ID for the web site
 175 > oauth_application: "SGm8QJ6tmoPXEaUPIZzLUmm1iujltYZVWCp9hvGsqXg"
 176 > # OAuth 2 Client Secret for the web site
 177 > oauth_key: "eRHPm4GtEnw9ovB1Iw7EcCLGtUb66bXbAAspv3aJxlI"
 178 > ```
 179
 180 ## Development Tools
 181
 182 ### Viewing Rails Logs
 183
 184 Rails has its own log. To inspect the log during development:
 185
 186 ```bash
 187 tail -f log/development.log
 188 ```
 189
 190 ### Maintaining Your Installation
 191
 192 > [!TIP]
 193 > If your installation stops working for some reason:
 194 >
 195 > - **Update gems:** Sometimes the bundle has been updated. Go to your `openstreetmap-website` directory and run:
 196 >   ```bash
 197 >   bundle install
 198 >   ```
 199 >
 200 > - **Update Node.js modules:** If Node.js modules have been updated, run:
 201 >   ```bash
 202 >   bundle exec bin/yarn install
 203 >   ```
 204 >
 205 > - **Run database migrations:** The OSM database schema is changed periodically. To keep up with improvements:
 206 >   ```bash
 207 >   bundle exec rails db:migrate
 208 >   ```
 209
 210 ## Production Deployment
 211
 212 If you want to deploy `openstreetmap-website` for production use, you'll need to make several changes:
 213
 214 ### Web Server Configuration
 215
 216 > [!WARNING]
 217 > Don't use `rails server` in production. Our recommended approach is to use [Phusion Passenger](https://www.phusionpassenger.com/).
 218
 219 - Instructions are available for [setting it up with most web servers](https://www.phusionpassenger.com/documentation_and_support#documentation)
 220 - Passenger will, by design, use the Production environment and therefore the production database - make sure it contains the appropriate data and user accounts
 221
 222 ### Performance Optimizations
 223
 224 > [!TIP]
 225 > **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.
 226
 227 ### Asset Compilation
 228
 229 - **Generate i18n files and precompile assets:**
 230   ```bash
 231   RAILS_ENV=production bundle exec i18n export
 232   bundle exec rails assets:precompile
 233   ```
 234
 235 ### File Permissions
 236
 237 > [!IMPORTANT]
 238 > Make sure the web server user as well as the rails user can read, write and create directories in `tmp/`.
 239
 240 ### Testing on the OSM Dev Server
 241
 242 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).
 243
 244 ## Troubleshooting
 245
 246 If you have problems with your configuration:
 247
 248 - **Check the Rails log:** Use `tail -f log/development.log` to see what's happening
 249 - **Verify database connectivity:** Ensure PostgreSQL is running and accessible
 250 - **Check file permissions:** Make sure the Rails application can read/write necessary files
 251 - **Review OAuth settings:** Ensure Client IDs and secrets are correctly configured
 252
 253 ### Getting Help
 254
 255 If you need additional assistance:
 256 - **Mailing list:** Ask on the [rails-dev@openstreetmap.org mailing list](https://lists.openstreetmap.org/listinfo/rails-dev)
 257 - **IRC:** Join the [#osm-dev IRC Channel](https://wiki.openstreetmap.org/wiki/IRC)
 258
 259 ## Contributing
 260
 261 For information on contributing changes to the code, see [CONTRIBUTING.md](CONTRIBUTING.md)