doc/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 Many features of the website require a user. The following script can get you started:
  54
  55 ```bash
  56 $ bundle exec rails dev:populate
  57 ```
  58
  59 This will create two users: `admin` (with administrator privileges) and `mapper` (with normal privileges). For either of them, the password is `password` (feel free to change it).
  60
  61 Alternatively, you can create users manually using the web interface at [http://localhost:3000/user/new](http://localhost:3000/user/new). If you go this route, you may need to perform additional user management tasks. At the very least, new users need to be activated in order to sign in. You can do this via the Rails console as follows.
  62
  63 ### Managing Users via Rails Console
  64
  65 1. **Enter the Rails console:**
  66    ```bash
  67    $ bundle exec rails console
  68    ```
  69
  70 2. **Find the user:**
  71    ```ruby
  72    >> user = User.find_by(:display_name => "My New User Name")
  73    => #[ ... ]
  74    ```
  75
  76 3. **Modify the user as desired:**
  77
  78    **Activate/confirm the user:**
  79    ```ruby
  80    >> user.activate!
  81    => true
  82    ```
  83
  84    **Grant moderator role:**
  85    ```ruby
  86    >> user.roles.create(:role => "moderator", :granter_id => user.id)
  87    => #[ ... ]
  88    ```
  89
  90    **Grant administrator role:**
  91    ```ruby
  92    >> user.roles.create(:role => "administrator", :granter_id => user.id)
  93    => #[ ... ]
  94    ```
  95
  96 4. **Exit the Rails console:**
  97    ```ruby
  98    >> quit
  99    ```
 100
 101 ## OAuth Setup
 102
 103 There are two built-in applications which communicate via the API, and therefore need to be registered as OAuth 2 applications. These are:
 104
 105 * **iD** - the web-based editor
 106 * **The website itself** - for the Notes functionality
 107
 108 If you used the `dev:populate` script to create your initial users, this step should not be necessary.
 109
 110 Otherwise, 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.
 111
 112 ### Automated OAuth Setup (Recommended)
 113
 114 > [!TIP]
 115 > You can register both applications automatically by running the following rake task:
 116 >
 117 > ```bash
 118 > bundle exec rails oauth:register_apps["My New User Name"]
 119 > ```
 120 >
 121 > 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.
 122
 123 Alternatively you can register the applications manually, as described in the next section.
 124
 125 ### Setting up OAuth for iD
 126
 127 1. **Navigate to OAuth applications:**
 128    - Go to "[OAuth 2 applications](http://localhost:3000/oauth2/applications)" on the My Account page
 129
 130 2. **Register new application:**
 131    - Click on "Register new application"
 132    - **Name:** "Local iD"
 133    - **Redirect URIs:** "http://localhost:3000" (unless you have set up alternatives)
 134
 135 3. **Select permissions:**
 136    Check boxes for the following:
 137    - ✅ 'Read user preferences'
 138    - ✅ 'Modify user preferences'
 139    - ✅ 'Modify the map'
 140    - ✅ 'Read private GPS traces'
 141    - ✅ 'Upload GPS traces'
 142    - ✅ 'Modify notes'
 143
 144 4. **Configure the application:**
 145    - Copy the "Client ID" from the next page
 146    - Edit `config/settings.local.yml` in your rails tree
 147    - Add the "id_application" configuration with the "Client ID" as the value
 148    - Restart your rails server
 149
 150 > [!TIP]
 151 > **Example configuration in `settings.local.yml`:**
 152 > ```yaml
 153 > # Default editor
 154 > default_editor: "id"
 155 > # OAuth 2 Client ID for iD
 156 > id_application: "Snv…OA0"
 157 > ```
 158
 159 ### Setting up OAuth for Notes and Changeset Discussions
 160
 161 To allow [Notes](https://wiki.openstreetmap.org/wiki/Notes) and changeset discussions to work:
 162
 163 1. **Register OAuth application for the website:**
 164    - Go to "[OAuth 2 applications](http://localhost:3000/oauth2/applications)" on the My Account page
 165    - Click on "Register new application"
 166    - **Name:** "OpenStreetMap Web Site"
 167    - **Redirect URIs:** "http://localhost:3000"
 168
 169 2. **Select permissions:**
 170    Check boxes for:
 171    - ✅ 'Modify the map'
 172    - ✅ 'Modify notes'
 173
 174 3. **Configure the application:**
 175    - Copy both the "Client Secret" and "Client ID"
 176    - Edit `config/settings.local.yml`
 177    - Add both configurations
 178    - Restart your rails server
 179
 180 > [!TIP]
 181 > **Example configuration in `settings.local.yml`:**
 182 > ```yaml
 183 > # OAuth 2 Client ID for the web site
 184 > oauth_application: "SGm8QJ6tmoPXEaUPIZzLUmm1iujltYZVWCp9hvGsqXg"
 185 > # OAuth 2 Client Secret for the web site
 186 > oauth_key: "eRHPm4GtEnw9ovB1Iw7EcCLGtUb66bXbAAspv3aJxlI"
 187 > ```
 188
 189 ## Development Tools
 190
 191 ### Viewing Rails Logs
 192
 193 Rails has its own log. To inspect the log during development:
 194
 195 ```bash
 196 tail -f log/development.log
 197 ```
 198
 199 ### Email Previews
 200
 201 We use [ActionMailer Previews](https://guides.rubyonrails.org/action_mailer_basics.html#previewing-and-testing-mailers) to generate previews of the emails sent by the application. Visit [http://localhost:3000/rails/mailers](http://localhost:3000/rails/mailers) to see the list of available previews.
 202
 203 ### Maintaining Your Installation
 204
 205 > [!TIP]
 206 > If your installation stops working for some reason:
 207 >
 208 > - **Update gems:** Sometimes the bundle has been updated. Go to your `openstreetmap-website` directory and run:
 209 >   ```bash
 210 >   bundle install
 211 >   ```
 212 >
 213 > - **Update Node.js modules:** If Node.js modules have been updated, run:
 214 >   ```bash
 215 >   bundle exec bin/yarn install
 216 >   ```
 217 >
 218 > - **Run database migrations:** The OSM database schema is changed periodically. To keep up with improvements:
 219 >   ```bash
 220 >   bundle exec rails db:migrate
 221 >   ```
 222
 223 ## Production Deployment
 224
 225 If you want to deploy `openstreetmap-website` for production use, you'll need to make several changes:
 226
 227 ### Web Server Configuration
 228
 229 > [!WARNING]
 230 > Don't use `rails server` in production. Our recommended approach is to use [Phusion Passenger](https://www.phusionpassenger.com/).
 231
 232 - Instructions are available for [setting it up with most web servers](https://www.phusionpassenger.com/documentation_and_support#documentation)
 233 - Passenger will, by design, use the Production environment and therefore the production database - make sure it contains the appropriate data and user accounts
 234
 235 ### Performance Optimizations
 236
 237 > [!TIP]
 238 > **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.
 239
 240 ### Asset Compilation
 241
 242 - **Generate i18n files and precompile assets:**
 243   ```bash
 244   RAILS_ENV=production bundle exec i18n export
 245   bundle exec rails assets:precompile
 246   ```
 247
 248 ### File Permissions
 249
 250 > [!IMPORTANT]
 251 > Make sure the web server user as well as the rails user can read, write and create directories in `tmp/`.
 252
 253 ### Testing on the OSM Dev Server
 254
 255 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).
 256
 257 ## Troubleshooting
 258
 259 If you have problems with your configuration:
 260
 261 - **Check the Rails log:** Use `tail -f log/development.log` to see what's happening
 262 - **Verify database connectivity:** Ensure PostgreSQL is running and accessible
 263 - **Check file permissions:** Make sure the Rails application can read/write necessary files
 264 - **Review OAuth settings:** Ensure Client IDs and secrets are correctly configured
 265
 266 ### Getting Help
 267
 268 If you need additional assistance:
 269 - **Mailing list:** Ask on the [rails-dev@openstreetmap.org mailing list](https://lists.openstreetmap.org/listinfo/rails-dev)
 270 - **IRC:** Join the [#osm-dev IRC Channel](https://wiki.openstreetmap.org/wiki/IRC)
 271
 272 ## Contributing
 273
 274 For information on contributing changes to the code, see [CONTRIBUTING.md](../CONTRIBUTING.md)