CONFIGURE.md

   1 # Configuration
   2
   3 After [installing](INSTALL.md) this software, you may need to carry out some of these configuration steps, depending on your tasks.
   4
   5 ## Application configuration
   6
   7 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`
   8
   9 ## Populating the database
  10
  11 Your installation comes with no geographic data loaded. You can either create new data using one of the editors (iD, JOSM etc) or by loading an OSM extract.
  12
  13 After installing but before creating any users or data, 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.
  14
  15 ```
  16 osmosis --read-pbf greater-london-latest.osm.pbf \
  17   --write-apidb host="localhost" database="openstreetmap" \
  18   user="openstreetmap" password="" validateSchemaVersion="no"
  19 ```
  20
  21 Loading an apidb database with Osmosis is about **twenty** times slower than loading the equivalent data with osm2pgsql into a rendering database. [``--log-progress``](https://wiki.openstreetmap.org/wiki/Osmosis/Detailed_Usage#--log-progress_.28--lp.29) may be desirable for status updates.
  22
  23 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).
  24
  25 ## Managing Users
  26
  27 If you create a user by signing up to your local website, you need to confirm the user before you can log in, which normally happens by clicking a link sent via email. If don't want to set up your development box to send emails to public email addresses then you can create the user as normal and then confirm it manually through the Rails console:
  28
  29 ```
  30 $ bundle exec rails console
  31 >> user = User.find_by(:display_name => "My New User Name")
  32 => #[ ... ]
  33 >> user.activate!
  34 => true
  35 >> quit
  36 ```
  37
  38 ### Giving Administrator/Moderator Permissions
  39
  40 To give administrator or moderator permissions:
  41
  42 ```
  43 $ bundle exec rails console
  44 >> user = User.find_by(:display_name => "My New User Name")
  45 => #[ ... ]
  46 >> user.roles.create(:role => "administrator", :granter_id => user.id)
  47 => #[ ... ]
  48 >> user.roles.create(:role => "moderator", :granter_id => user.id)
  49 => #[ ... ]
  50 >> user.save!
  51 => true
  52 >> quit
  53 ```
  54
  55 ## OAuth Consumer Keys
  56
  57 There are two built-in applications which communicate via the API, and therefore need to be registered as OAuth 2 applications. These are:
  58
  59 * iD
  60 * The website itself (for the Notes functionality)
  61
  62 For iD, do the following:
  63
  64 * Go to "[OAuth 2 applications](http://localhost:3000/oauth2/applications)" on the My settings page.
  65 * Click on "Register new application".
  66 * Unless you have set up alternatives, use Name: "Local iD" and Main Application URL: "http://localhost:3000"
  67 * Check boxes for the following Permissions
  68   * 'Read user preferences'
  69   * 'Modify user preferences'
  70   * 'Modify the map'
  71   * 'Read private GPS traces'
  72   * 'Upload GPS traces'
  73   * 'Modify notes'
  74 * On the next page, copy the "Client ID"
  75 * Edit config/settings.local.yml in your rails tree
  76 * Add the "id_application" configuration with the "Client ID" as the value
  77 * Restart your rails server
  78
  79 An example excerpt from settings.local.yml:
  80
  81 ```
  82 # Default editor
  83 default_editor: "id"
  84 # OAuth 2 Client ID for iD
  85 id_application: "Snv…OA0"
  86 ```
  87
  88 To allow [Notes](https://wiki.openstreetmap.org/wiki/Notes) and changeset discussions to work, follow a similar process, this time registering an OAuth 2 application for the web site:
  89
  90 * Go to "[OAuth 2 applications](http://localhost:3000/oauth2/applications)" on the My settings page.
  91 * Click on "Register new application".
  92 * Use Name: "OpenStreetMap Web Site" and Redirect URIs: "http://localhost:3000"
  93 * Check boxes for the following Permissions
  94   * 'Modify the map'
  95   * 'Modify notes'
  96 * On the next page, copy the "Client Secret" and "Client ID"
  97 * Edit config/settings.local.yml in your rails tree
  98 * Add the "oauth_application" configuration with the "Client ID" as the value
  99 * Add the "oauth_key" configuration with the "Client Secret" as the value
 100 * Restart your rails server
 101
 102 An example excerpt from settings.local.yml:
 103
 104 ```
 105 # OAuth 2 Client ID for the web site
 106 oauth_application: "SGm8QJ6tmoPXEaUPIZzLUmm1iujltYZVWCp9hvGsqXg"
 107 # OAuth 2 Client Secret for the web site
 108 oauth_key: "eRHPm4GtEnw9ovB1Iw7EcCLGtUb66bXbAAspv3aJxlI"
 109 ```
 110
 111 ## Troubleshooting
 112
 113 Rails has its own log.  To inspect the log, do this:
 114
 115 ```
 116 tail -f log/development.log
 117 ```
 118
 119 If you have more problems, please ask on the [rails-dev@openstreetmap.org mailing list](https://lists.openstreetmap.org/listinfo/rails-dev) or on the [#osm-dev IRC Channel](https://wiki.openstreetmap.org/wiki/IRC)
 120
 121 ## Maintaining your installation
 122
 123 If your installation stops working for some reason:
 124
 125 * Sometimes gem dependencies change. To update go to your `openstreetmap-website` directory and run ''bundle install'' as root.
 126
 127 * The OSM database schema is changed periodically and you need to keep up with these improvements. Go to your `openstreetmap-website` directory and run:
 128
 129 ```
 130 bundle exec rails db:migrate
 131 ```
 132
 133 ## Testing on the osm dev server
 134
 135 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).
 136
 137 # Contributing
 138
 139 For information on contributing changes to the codes, see [CONTRIBUTING.md](CONTRIBUTING.md)
 140
 141 # Production Deployment
 142
 143 If you want to deploy `openstreetmap-website` for production use, you'll need to make a few changes.
 144
 145 * It's not recommended to use `rails server` in production. Our recommended approach is to use [Phusion Passenger](https://www.phusionpassenger.com/). Instructions are available for [setting it up with most web servers](https://www.phusionpassenger.com/documentation_and_support#documentation).
 146 * Passenger will, by design, use the Production environment and therefore the production database - make sure it contains the appropriate data and user accounts.
 147 * 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.
 148 * Make sure you generate the i18n files and precompile the production assets: `RAILS_ENV=production rails i18n:js:export assets:precompile`
 149 * Make sure the web server user as well as the rails user can read, write and create directories in `tmp/`.