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 ## Populating the database
   6
   7 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.
   8
   9 * Use this [yet-to-be-written script](https://github.com/openstreetmap/openstreetmap-website/issues/282)
  10
  11 ## Managing Users
  12
  13 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:
  14
  15 ```
  16 $ bundle exec rails console
  17 >> user = User.find_by_display_name("My New User Name")
  18 => #[ ... ]
  19 >> user.status = "active"
  20 => "active"
  21 >> user.save!
  22 => true
  23 >> quit
  24 ```
  25
  26 ### Giving Administrator/Moderator Permissions
  27
  28 To give administrator or moderator permissions:
  29
  30 ```
  31 $ bundle exec rails console
  32 >> user = User.find_by_display_name("My New User Name")
  33 => #[ ... ]
  34 >> user.roles.create( {:role => "administrator", :granter_id => user.id}, :without_protection => true)
  35 => #[ ... ]
  36 >> user.roles.create( {:role => "moderator", :granter_id => user.id}, :without_protection => true)
  37 => #[ ... ]
  38 >> user.save!
  39 => true
  40 >> quit
  41 ```
  42
  43 ## OAuth Consumer Keys
  44
  45 Three of the built-in applications communicate via the API, and therefore need OAuth consumer keys configured. These are:
  46
  47 * Potlatch 2
  48 * iD
  49 * The website itself (for the Notes functionality)
  50
  51 For example, to use the Potlatch 2 editor you need to register it as an OAuth application.
  52
  53 Do the following:
  54 * Log into your Rails Port instance - e.g. http://localhost:3000
  55 * Click on your user name to go to your user page
  56 * Click on "my settings" on the user page
  57 * Click on "oauth settings" on the My settings page
  58 * Click on 'Register your application'.
  59 * Unless you have set up alternatives, use Name: "Local Potlatch" and URL: "http://localhost:3000"
  60 * Check the 'modify the map' box.
  61 * Everything else can be left with the default blank values.
  62 * Click the "Register" button
  63 * On the next page, copy the "consumer key"
  64 * Edit config/application.yml in your rails tree
  65 * Uncomment and change the "potlatch2_key" configuration value
  66 * Restart your rails server
  67
  68 An example excerpt from application.yml:
  69
  70 ```
  71 # Default editor
  72 default_editor: "potlatch2"
  73 # OAuth consumer key for Potlatch 2
  74 potlatch2_key: "8lFmZPsagHV4l3rkAHq0hWY5vV3Ctl3oEFY1aXth"
  75 ```
  76
  77 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.
  78
  79 ## Troubleshooting
  80
  81 Rails has its own log.  To inspect the log, do this:
  82
  83 ```
  84 tail -f log/development.log
  85 ```
  86
  87 If you have more problems, please ask on the [rails-dev@openstreetmap.org mailing list](http://lists.openstreetmap.org/listinfo/rails-dev) or on the [#osm-dev IRC Channel](http://wiki.openstreetmap.org/wiki/IRC)
  88
  89 ## Maintaining your installation
  90
  91 If your installation stops working for some reason:
  92
  93 * Sometimes gem dependencies change. To update go to your rails_port directory and run ''bundle install'' as root.
  94
  95 * The OSM database schema is changed periodically and you need to keep up with these improvements. Go to your rails_port directory and run:
  96
  97 ```
  98 bundle exec rake db:migrate
  99 ```
 100
 101 ## Testing on the osm dev server
 102
 103 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](http://wiki.openstreetmap.org/wiki/Using_the_dev_server#Rails_Applications).
 104
 105 # Contributing
 106
 107 For information on contributing changes to the codes, see [CONTRIBUTING.md](CONTRIBUTING.md)
 108
 109 # Production Deployment
 110
 111 If you want to deploy The Rails Port for production use, you'll need to make a few changes.
 112
 113 * It's not recommended to use `rails server` in production. Our recommended approach is to use [Phusion Passenger](https://www.phusionpassenger.com/).
 114 * Passenger will, by design, use the Production environment and therefore the production database - make sure it contains the appropriate data and user accounts.
 115 * Your production database will also need the extensions and functions installed - see [INSTALL.md](INSTALL.md)
 116 * 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.
 117 * The included version of the GPX importer is slow and/or completely inoperable. You should consider using [the high-speed GPX importer](http://git.openstreetmap.org/gpx-import.git/).