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 ### Email Previews
 193
 194 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.
 195
 196 ### Maintaining Your Installation
 197
 198 > [!TIP]
 199 > If your installation stops working for some reason:
 200 >
 201 > - **Update gems:** Sometimes the bundle has been updated. Go to your `openstreetmap-website` directory and run:
 202 >   ```bash
 203 >   bundle install
 204 >   ```
 205 >
 206 > - **Update Node.js modules:** If Node.js modules have been updated, run:
 207 >   ```bash
 208 >   bundle exec bin/yarn install
 209 >   ```
 210 >
 211 > - **Run database migrations:** The OSM database schema is changed periodically. To keep up with improvements:
 212 >   ```bash
 213 >   bundle exec rails db:migrate
 214 >   ```
 215
 216 ## Production Deployment
 217
 218 If you want to deploy `openstreetmap-website` for production use, you'll need to make several changes:
 219
 220 ### Web Server Configuration
 221
 222 > [!WARNING]
 223 > Don't use `rails server` in production. Our recommended approach is to use [Phusion Passenger](https://www.phusionpassenger.com/).
 224
 225 - Instructions are available for [setting it up with most web servers](https://www.phusionpassenger.com/documentation_and_support#documentation)
 226 - Passenger will, by design, use the Production environment and therefore the production database - make sure it contains the appropriate data and user accounts
 227
 228 ### Performance Optimizations
 229
 230 > [!TIP]
 231 > **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.
 232
 233 ### Asset Compilation
 234
 235 - **Generate i18n files and precompile assets:**
 236   ```bash
 237   RAILS_ENV=production bundle exec i18n export
 238   bundle exec rails assets:precompile
 239   ```
 240
 241 ### File Permissions
 242
 243 > [!IMPORTANT]
 244 > Make sure the web server user as well as the rails user can read, write and create directories in `tmp/`.
 245
 246 ### Testing on the OSM Dev Server
 247
 248 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).
 249
 250 ## Troubleshooting
 251
 252 If you have problems with your configuration:
 253
 254 - **Check the Rails log:** Use `tail -f log/development.log` to see what's happening
 255 - **Verify database connectivity:** Ensure PostgreSQL is running and accessible
 256 - **Check file permissions:** Make sure the Rails application can read/write necessary files
 257 - **Review OAuth settings:** Ensure Client IDs and secrets are correctly configured
 258
 259 ### Getting Help
 260
 261 If you need additional assistance:
 262 - **Mailing list:** Ask on the [rails-dev@openstreetmap.org mailing list](https://lists.openstreetmap.org/listinfo/rails-dev)
 263 - **IRC:** Join the [#osm-dev IRC Channel](https://wiki.openstreetmap.org/wiki/IRC)
 264
 265 ## Contributing
 266
 267 For information on contributing changes to the code, see [CONTRIBUTING.md](CONTRIBUTING.md)