Merge remote-tracking branch 'upstream/pull/5231'

[rails.git] / CONFIGURE.md

diff --git a/CONFIGURE.md b/CONFIGURE.md
index 598ea3f65d9207c25a3d7f6380c9b5319c9f2da3..dcc8ae2ac1d20a5001ae568a2dbf17b18735ab48 100644 (file)
--- a/CONFIGURE.md
+++ b/CONFIGURE.md
@@ -4,11 +4,11 @@ After [installing](INSTALL.md) this software, you may need to carry out some of
 
 ## Application configuration
 
 
 ## Application configuration
 

-Many settings are available in `config/settings.yml`. You can customize your installation of The Rails Port by overriding these values using `config/settings.local.yml`
+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`

 
 ## Populating the database
 
 
 ## Populating the database
 

-Your installation comes with no geographic data loaded. You can either create new data using one of the editors (Potlatch 2, iD, JOSM etc) or by loading an OSM extract.
+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.

 
 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.
 
 
 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.
 


@@ -28,11 +28,9 @@ If you create a user by signing up to your local website, you need to confirm th
 
 ```
 $ bundle exec rails console
 
 ```
 $ bundle exec rails console

->> user = User.find_by_display_name("My New User Name")
+>> user = User.find_by(:display_name => "My New User Name")

 => #[ ... ]
 => #[ ... ]

->> user.status = "active"
-=> "active"
->> user.save!
+>> user.activate!

 => true
 >> quit
 ```
 => true
 >> quit
 ```


@@ -43,52 +41,70 @@ To give administrator or moderator permissions:
 
 ```
 $ bundle exec rails console
 
 ```
 $ bundle exec rails console

->> user = User.find_by_display_name("My New User Name")
+>> user = User.find_by(:display_name => "My New User Name")

 => #[ ... ]
 >> user.roles.create(:role => "administrator", :granter_id => user.id)
 => #[ ... ]
 >> user.roles.create(:role => "moderator", :granter_id => user.id)
 => #[ ... ]
 => #[ ... ]
 >> user.roles.create(:role => "administrator", :granter_id => user.id)
 => #[ ... ]
 >> user.roles.create(:role => "moderator", :granter_id => user.id)
 => #[ ... ]

->> user.save!
-=> true

 >> quit
 ```
 
 ## OAuth Consumer Keys
 
 >> quit
 ```
 
 ## OAuth Consumer Keys
 

-Three of the built-in applications communicate via the API, and therefore need OAuth consumer keys configured. These are:
+There are two built-in applications which communicate via the API, and therefore need to be registered as OAuth 2 applications. These are:

 
 

-* Potlatch 2

 * iD
 * The website itself (for the Notes functionality)
 
 * iD
 * The website itself (for the Notes functionality)
 

-For example, to use the Potlatch 2 editor you need to register it as an OAuth application.
-
-Do the following:
-* Log into your Rails Port instance - e.g. http://localhost:3000
-* Click on your user name to go to your user page
-* Click on "my settings" on the user page
-* Click on "oauth settings" on the My settings page
-* Click on 'Register your application'.
-* Unless you have set up alternatives, use Name: "Local Potlatch" and URL: "http://localhost:3000"
-* Check the 'modify the map' box.
-* Everything else can be left with the default blank values.
-* Click the "Register" button
-* On the next page, copy the "consumer key"
+For iD, do the following:
+
+* Go to "[OAuth 2 applications](http://localhost:3000/oauth2/applications)" on the My settings page.
+* Click on "Register new application".
+* Unless you have set up alternatives, use Name: "Local iD" and Redirect URIs: "http://localhost:3000"
+* Check boxes for the following Permissions
+  * 'Read user preferences'
+  * 'Modify user preferences'
+  * 'Modify the map'
+  * 'Read private GPS traces'
+  * 'Upload GPS traces'
+  * 'Modify notes'
+* On the next page, copy the "Client ID"

 * Edit config/settings.local.yml in your rails tree
 * Edit config/settings.local.yml in your rails tree

-* Add the "potlatch2_key" configuration key and the consumer key as the value
+* Add the "id_application" configuration with the "Client ID" as the value

 * Restart your rails server
 
 An example excerpt from settings.local.yml:
 
 ```
 # Default editor
 * Restart your rails server
 
 An example excerpt from settings.local.yml:
 
 ```
 # Default editor

-default_editor: "potlatch2"
-# OAuth consumer key for Potlatch 2
-potlatch2_key: "8lFmZPsagHV4l3rkAHq0hWY5vV3Ctl3oEFY1aXth"
+default_editor: "id"
+# OAuth 2 Client ID for iD
+id_application: "Snv…OA0"

 ```
 
 ```
 

-Follow the same process for registering and configuring iD (`id_key`) and the website/Notes (`oauth_key`), or to save time, simply reuse the same consumer key for each.
+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:
+
+* Go to "[OAuth 2 applications](http://localhost:3000/oauth2/applications)" on the My settings page.
+* Click on "Register new application".
+* Use Name: "OpenStreetMap Web Site" and Redirect URIs: "http://localhost:3000"
+* Check boxes for the following Permissions
+  * 'Modify the map'
+  * 'Modify notes'
+* On the next page, copy the "Client Secret" and "Client ID"
+* Edit config/settings.local.yml in your rails tree
+* Add the "oauth_application" configuration with the "Client ID" as the value
+* Add the "oauth_key" configuration with the "Client Secret" as the value
+* Restart your rails server
+
+An example excerpt from settings.local.yml:
+
+```
+# OAuth 2 Client ID for the web site
+oauth_application: "SGm8QJ6tmoPXEaUPIZzLUmm1iujltYZVWCp9hvGsqXg"
+# OAuth 2 Client Secret for the web site
+oauth_key: "eRHPm4GtEnw9ovB1Iw7EcCLGtUb66bXbAAspv3aJxlI"
+```

 
 ## Troubleshooting
 
 
 ## Troubleshooting
 


@@ -104,17 +120,17 @@ If you have more problems, please ask on the [rails-dev@openstreetmap.org mailin
 
 If your installation stops working for some reason:
 
 
 If your installation stops working for some reason:
 

-* Sometimes gem dependencies change. To update go to your rails_port directory and run ''bundle install'' as root.
+* Sometimes gem dependencies change. To update go to your `openstreetmap-website` directory and run ''bundle install'' as root.

 
 

-* The OSM database schema is changed periodically and you need to keep up with these improvements. Go to your rails_port directory and run:
+* The OSM database schema is changed periodically and you need to keep up with these improvements. Go to your `openstreetmap-website` directory and run:

 
 ```
 
 ```

-bundle exec rake db:migrate
+bundle exec rails db:migrate

 ```
 
 ## Testing on the osm dev server
 
 ```
 
 ## Testing on the osm dev server
 

-For example, after developing a patch for the rails_port, you might want to demonstrate it to others or ask for comments and testing. To do this one can [set up an instance of the rails_port on the dev server in ones user directory](https://wiki.openstreetmap.org/wiki/Using_the_dev_server#Rails_Applications).
+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).

 
 # Contributing
 
 
 # Contributing
 


@@ -122,13 +138,10 @@ For information on contributing changes to the codes, see [CONTRIBUTING.md](CONT
 
 # Production Deployment
 
 
 # Production Deployment
 

-If you want to deploy The Rails Port for production use, you'll need to make a few changes.
+If you want to deploy `openstreetmap-website` for production use, you'll need to make a few changes.

 
 * 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).
 * Passenger will, by design, use the Production environment and therefore the production database - make sure it contains the appropriate data and user accounts.
 
 * 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).
 * Passenger will, by design, use the Production environment and therefore the production database - make sure it contains the appropriate data and user accounts.

-* Your production database will also need the extensions and functions installed - see [INSTALL.md](INSTALL.md)

 * 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.
 * 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.

-* Make sure you generate the i18n files and precompile the production assets: `RAILS_ENV=production rake i18n:js:export assets:precompile`
+* Make sure you generate the i18n files and precompile the production assets: `RAILS_ENV=production rails i18n:js:export assets:precompile`

 * Make sure the web server user as well as the rails user can read, write and create directories in `tmp/`.
 * Make sure the web server user as well as the rails user can read, write and create directories in `tmp/`.

-* If you want to use diff replication then you might want to consider installing the shared library special SQL functions for the `xid_to_int4` function. A pure SQL version is available, but may become a performance issue on large databases with a high rate of changes. Note that you will need a version of PostgreSQL < 9.6 (yes, _less than_) to use `xid` indexing, whether pure SQL or shared library.
-* If you expect to serve a lot of `/changes` API calls, then you might also want to install the shared library versions of the SQL functions.