]> git.openstreetmap.org Git - rails.git/blob - CONFIGURE.md
Merge remote-tracking branch 'upstream/pull/3544'
[rails.git] / 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 The Rails Port 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 OAuth consumer keys configured. These are:
58
59 * iD
60 * The website itself (for the Notes functionality)
61
62 To use the iD editor you need to register it as an OAuth 1 application.
63
64 Do the following:
65 * Log into your Rails Port instance - e.g. http://localhost:3000
66 * Click on your user name to go to your user page
67 * Click on "my settings" on the user page
68 * Click on "OAuth 1 settings" on the My settings page
69 * Click on 'Register your application'.
70 * Unless you have set up alternatives, use Name: "Local iD" and Main Application URL: "http://localhost:3000"
71 * Check boxes for the following Permissions
72   * 'read their user preferences'
73   * 'modify the map'
74   * 'read their private GPS traces'
75   * 'modify notes'
76 * Everything else can be left with the default blank values.
77 * Click the "Register" button
78 * On the next page, copy the "consumer key"
79 * Edit config/settings.local.yml in your rails tree
80 * Add the "id_key" configuration key and the consumer key as the value
81 * Restart your rails server
82
83 An example excerpt from settings.local.yml:
84
85 ```
86 # Default editor
87 default_editor: "id"
88 # OAuth 1 consumer key for iD
89 id_key: "8lFmZPsagHV4l3rkAHq0hWY5vV3Ctl3oEFY1aXth"
90 ```
91
92 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:
93
94 * Go to "[OAuth 2 applications](http://localhost:3000/oauth2/applications)" on the My settings page.
95 * Click on "Register new application".
96 * Use Name: "OpenStreetMap Web Site" and Redirect URIs: "http://localhost:3000"
97 * Check boxes for the following Permissions
98   * 'Modify the map'
99   * 'Modify notes'
100 * On the next page, copy the "Client Secret" and "Client ID"
101 * Edit config/settings.local.yml in your rails tree
102 * Add the "oauth_application" configuration with the "Client ID" as the value
103 * Add the "oauth_key" configuration with the "Client Secret" as the value
104 * Restart your rails server
105
106 An example excerpt from settings.local.yml:
107
108 ```
109 # OAuth 2 Client ID for the web site
110 oauth_application: "SGm8QJ6tmoPXEaUPIZzLUmm1iujltYZVWCp9hvGsqXg"
111 # OAuth 2 Client Secret for the web site
112 oauth_key: "eRHPm4GtEnw9ovB1Iw7EcCLGtUb66bXbAAspv3aJxlI"
113 ```
114
115 ## Troubleshooting
116
117 Rails has its own log.  To inspect the log, do this:
118
119 ```
120 tail -f log/development.log
121 ```
122
123 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)
124
125 ## Maintaining your installation
126
127 If your installation stops working for some reason:
128
129 * Sometimes gem dependencies change. To update go to your rails_port directory and run ''bundle install'' as root.
130
131 * The OSM database schema is changed periodically and you need to keep up with these improvements. Go to your rails_port directory and run:
132
133 ```
134 bundle exec rake db:migrate
135 ```
136
137 ## Testing on the osm dev server
138
139 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).
140
141 # Contributing
142
143 For information on contributing changes to the codes, see [CONTRIBUTING.md](CONTRIBUTING.md)
144
145 # Production Deployment
146
147 If you want to deploy The Rails Port for production use, you'll need to make a few changes.
148
149 * 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).
150 * Passenger will, by design, use the Production environment and therefore the production database - make sure it contains the appropriate data and user accounts.
151 * Your production database will also need the extensions and functions installed - see [INSTALL.md](INSTALL.md)
152 * 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.
153 * Make sure you generate the i18n files and precompile the production assets: `RAILS_ENV=production rake i18n:js:export assets:precompile`
154 * Make sure the web server user as well as the rails user can read, write and create directories in `tmp/`.
155 * 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.