Improve installation documentation and add contributor instructions

2013-09-09 16:42:11 +01:00 · 2013-09-09 16:42:11 +01:00 · c3d7cfd7ff
commit c3d7cfd7ff
parent 7e896d758d
5 changed files with 465 additions and 122 deletions
--- a/.gitignore
+++ b/.gitignore
@ -4,3 +4,4 @@ public/attachments
 tmp
 .DS_Store
 *~
+doc
--- a/CONFIGURE.md
+++ b/CONFIGURE.md
@ -0,0 +1,117 @@
+# Configuration
+
+After [installing](INSTALL.md) this software, you may need to carry out some of these configuration steps, depending on your tasks.
+
+## 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.
+
+* Use this [yet-to-be-written script](https://github.com/openstreetmap/openstreetmap-website/issues/282)
+
+## Managing Users
+
+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:
+
+```
+$ bundle exec rails console
+>> user = User.find_by_display_name("My New User Name")
+=> #[ ... ]
+>> user.status = "active"
+=> "active"
+>> user.save!
+=> true
+>> quit
+```
+
+### Giving Administrator/Moderator Permissions
+
+To give administrator or moderator permissions:
+
+```
+$ bundle exec rails console
+>> user = User.find_by_display_name("My New User Name")
+=> #[ ... ]
+>> user.roles.create( {:role => "administrator", :granter_id => user.id}, :without_protection => true)
+=> #[ ... ]
+>> user.roles.create( {:role => "moderator", :granter_id => user.id}, :without_protection => true)
+=> #[ ... ]
+>> user.save!
+=> true
+>> quit
+```
+
+## OAuth Consumer Keys
+
+Three of the built-in applications communicate via the API, and therefore need OAuth consumer keys configured. These are:
+
+* Potlatch 2
+* 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"
+* Edit config/application.yml in your rails tree
+* Uncomment and change the "potlatch2_key" configuration value
+* Restart your rails server
+
+An example excerpt from application.yml:
+
+```
+# Default editor
+default_editor: "potlatch2"
+# OAuth consumer key for Potlatch 2
+potlatch2_key: "8lFmZPsagHV4l3rkAHq0hWY5vV3Ctl3oEFY1aXth"
+```
+
+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.
+
+## Troubleshooting
+
+Rails has its own log.  To inspect the log, do this:
+
+```
+tail -f log/development.log
+```
+
+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)
+
+## Maintaining your installation
+
+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.
+
+* The OSM database schema is changed periodically and you need to keep up with these improvements. Go to your rails_port directory and run:
+
+```
+bundle exec rake db:migrate
+```
+
+## 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](http://wiki.openstreetmap.org/wiki/Using_the_dev_server#Rails_Applications).
+
+# Contributing
+
+For information on contributing changes to the codes, see [CONTRIBUTING.md](CONTRIBUTING.md)
+
+# Production Deployment
+
+If you want to deploy The Rails Port 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/).
+* 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 GPX importer is slow and/or completely inoperable. You should consider using [the high-speed GPX importer](http://git.openstreetmap.org/gpx-import.git/).
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@ -0,0 +1,99 @@
+* http://www.ruby-lang.org/ - The homepage of Ruby which has more links and some great tutorials.
+* http://rubyonrails.org/ - The homepage of Rails, also has links and tutorials
+
+## Coding style
+
+When writing code it is generally a good idea to try and match your
+formatting to that of any existing code in the same file, or to other
+similar files if you are writing new code. Consistency of layout is
+far more important that the layout itself as it makes reading code
+much easier.
+
+One golden rule of formatting -- please don't use tabs in your code
+as they will cause the file to be formatted differently for different
+people depending on how they have their editor configured.
+
+## Testing
+
+Having a good suite of tests is very important to the stability and
+maintainability of any code base. The tests in the Rails port code are
+by no means complete, but they are extensive, and must continue to be
+so with any new functionality which is written. Tests are also useful
+in giving others confidence in the code you've written, and can
+greatly speed up the process of merging in new code.
+
+When hacking, you should:
+
+* Write new tests to cover the new functionality you've added.
+* Where appropriate, modify existing tests to reflect new or changed
+functionality.
+* Never comment out or remove a test just because it doesn't pass.
+
+You can run the existing test suite with:
+
+```
+bundle exec rake test
+```
+
+You can generate test coverage stats with:
+
+```
+sudo gem install rcov
+rcov -x gems test/*/*.rb
+```
+
+The tests are automatically run on commit with the results shown at [http://cruise.openstreetmap.org/](http://cruise.openstreetmap.org/)
+
+## Comments
+
+Sometimes it's not apparent from the code itself what it does, or,
+more importantly, **why** it does that. Good comments help your fellow
+developers to read the code and satisfy themselves that it's doing the
+right thing.
+
+When hacking, you should:
+
+* Comment your code - don't go overboard, but explain the bits which
+might be difficult to understand what the code does, why it does it
+and why it should be the way it is.
+* Check existing comments to ensure that they are not misleading.
+
+## Code Documentation
+
+To generate the HTML documentation of the API/rails code, run the command
+
+```
+rake doc:app
+```
+
+## Committing
+
+When you submit patches, the project maintainer has to read them and
+understand them. This is difficult enough at the best of times, and
+misunderstanding patches can lead to them being more difficult to
+merge. To help with this, when submitting you should:
+
+* Split up large patches into smaller units of functionality.
+* Keep your commit messages relevant to the changes in each individual
+unit.
+
+When writing commit messages please try and stick to the same style as
+other commits, namely:
+
+* A one line summary, starting with a capital and with no full stop.
+* A blank line.
+* Full description, as proper sentences with capitals and full stops.
+
+For simple commits the one line summary is often enough and the body
+of the commit message can be left out.
+
+## Sending the patches
+
+If you have forked on GitHub then the best way to submit your patches is to
+push your changes back to GitHub and then send a "pull request" on GitHub.
+
+Otherwise you should either push your changes to a publicly visible git repository
+and send the details to the [rails-dev](http://lists.openstreetmap.org/listinfo/rails-dev)
+list or generate patches with `git format-patch` and send them to the
+[rails-dev](http://lists.openstreetmap.org/listinfo/rails-dev) list.
+
--- a/INSTALL.md
+++ b/INSTALL.md
@ -0,0 +1,222 @@
+# Installation
+
+These instructions are designed for setting up The Rails Port for development and testing.
+If you want to deploy the software for your own project, then see the notes at the end.
+
+These instructions are based on Ubuntu 12.04 LTS, which is the platform used by the OSMF servers.
+The instructions also work, with only minor amendments, for all other current Ubuntu releases, Fedora and MacOSX
+
+We don't recommend attempting to develop or deploy this software on Windows. If you need to use Windows, then
+try developing this sofware using Ubuntu in a virtual machine.
+
+## Dependencies
+
+Many of the dependencies are managed through the standard Ruby on Rails mechanisms -
+i.e. ruby gems specified in the Gemfile and installed using bundler. However, there are a large number
+of packages required before you can get the various gems installed.
+
+## Minimum requirements
+
+* Ruby 1.8.7 or 1.9.3
+* RubyGems 1.3.1+
+* Postgres 8.3+
+* ImageMagick
+* Bundler
+
+These can be installed on Ubuntu 10.10 or later with:
+
+```
+sudo apt-get install ruby libruby ruby-dev rdoc ri ruby-bundler rubygems \
+                     libmagickwand-dev libxml2-dev libxslt1-dev \
+                     apache2 apache2-threaded-dev build-essential git-core \
+                     postgresql postgresql-contrib libpq-dev postgresql-server-dev-all \
+                     libsasl2-dev
+```
+
+### Alternative platforms
+
+#### Fedora
+
+For Fedora, you can install the minimum requirements with:
+
+```
+sudo yum install ruby ruby-devel rubygem-rdoc rubygem-bundler rubygems \
+                 libxml2-devel \
+                 gcc gcc-c++ git \
+                 postgresql postgresql-server postgresql-contrib postgresql-devel \
+                 perl-podlators
+```
+
+If you didn't already have Postgres installed then create a Postgres instance and start the server:
+
+```
+sudo postgresql-setup initdb
+sudo systemctl start postgresql.service
+```
+
+Optionally set Postgres to start on boot:
+
+```
+sudo systemctl enable postgresql.service
+```
+
+#### MacOSX
+
+For MacOSX, you will need XCode installed from the Mac App Store; OS X 10.7 (Lion) or later; and some familiarity with Unix development via the Terminal.
+
+Installing Postgres:
+
+* Install Postgres.app from http://postgresapp.com/
+* Add Postgres to your path, by editing your profile:
+
+`nano ~/.profile`
+
+and adding:
+
+`export PATH=/Applications/Postgres.app/Contents/MacOS/bin:$PATH`
+
+Installing other dependencies:
+
+* Install Homebrew from http://mxcl.github.io/homebrew/
+* Install the latest version of Ruby: brew install ruby
+* Install ImageMagick: brew install imagemagick
+* Install Bundler: gem install bundler
+
+Note that OS X does not have a /home directory by default, so if you are using the GPX functions, you will need to change the directories specified in config/application.yml.
+
+## Cloning the repository
+
+The repository is reasonably large (~150MB) and it's unlikely that you need the full history. If you are happy to wait for it all to download, run:
+
+```
+git clone https://github.com/openstreetmap/openstreetmap-website.git
+```
+
+To clone only the most recent version (~23MB), instead use a 'shallow clone':
+
+```
+git clone --depth=1 https://github.com/openstreetmap/openstreetmap-website.git
+```
+
+If you want to add in the full history later on, perhaps to run `git blame` or `git log`, run `git fetch --depth=1000000`
+
+
+## Ruby gems
+
+We use [Bundler](http://gembundler.com/) to manage the rubygems required for the project.
+
+```
+cd openstreetmap-website
+bundle install
+```
+
+## Application setup
+
+We need to create the `config/application.yml` file from the example template. This contains various configuration options.
+
+```
+cp config/example.application.yml config/application.yml
+```
+
+You can customize your installation of The Rails Port by changing the values in `config/application.yml`
+
+## Database setup
+
+The Rails Port uses three databases -  one for development, one for testing, and one for production. The database-specific configuration
+options are stored in `config/database.yml`, which we need to create from the example template.
+
+```
+cp config/example.database.yml config/database.yml
+```
+
+PostgreSQL is configured to, by default, accept local connections without requiring a username or password. This is fine for development.
+If you wish to set up your database differently, then you should change the values found in the `config/database.yml` file, and amend the
+instructions below as appropriate.
+
+### PostgreSQL account setup
+
+We need to create a PostgreSQL role (i.e. user account) for your current user, and it needs to be a superuser so that we can create more database.
+
+```
+sudo -u postgres -i
+createuser -s <username>
+exit
+```
+
+### Create the databases
+
+To create the three databases - for development, testing and production - run:
+
+```
+bundle exec rake db:create
+```
+
+### PostgreSQL Btree-gist Extension
+
+We need to load the btree-gist extension, which is needed for showing changesets on the history tab.
+
+For PostgreSQL < 9.1 (change the version number in the path as necessary):
+
+```
+psql -d openstreetmap < /usr/share/postgresql/9.0/contrib/btree_gist.sql
+```
+
+For PostgreSQL >= 9.1:
+
+```
+psql -d openstreetmap -c "CREATE EXTENSION btree_gist"
+```
+
+### PostgreSQL Functions
+
+We need to install special functions into the postgresql databases, and these are provided by a library that needs compiling first.
+
+```
+cd db/functions
+make libpgosm.so
+cd ../..
+```
+
+Then we create the functions within each database. We're using `pwd` to substitute in the current working directory, since PostgreSQL needs the full path.
+
+```
+psql -d openstreetmap -c "CREATE FUNCTION maptile_for_point(int8, int8, int4) RETURNS int4 AS '`pwd`/db/functions/libpgosm', 'maptile_for_point' LANGUAGE C STRICT"
+psql -d openstreetmap -c "CREATE FUNCTION tile_for_point(int4, int4) RETURNS int8 AS '`pwd`/db/functions/libpgosm', 'tile_for_point' LANGUAGE C STRICT"
+psql -d openstreetmap -c "CREATE FUNCTION xid_to_int4(xid) RETURNS int4 AS '`pwd`/db/functions/libpgosm', 'xid_to_int4' LANGUAGE C STRICT"
+```
+
+### Database structure
+
+To create all the tables, indexes and constraints, run:
+
+```
+bundle exec rake db:migrate
+```
+
+## Running the tests
+
+To ensure that everything is set up properly, you should now run:
+
+```
+bundle exec rake test
+```
+
+This test will take a few minutes, reporting tests run, assertions, and any errors. If you receive no errors, then your installation is successful.
+
+The unit tests may output parser errors related to "Attribute lat redefined." These can be ignored.
+
+### Starting the server
+
+Rails comes with a built-in webserver, so that you can test on your own machine without needing a server. Run
+
+```
+bundle exec rails server
+```
+
+You can now view the site in your favourite web-browser at `http://localhost:3000/`
+
+Note that the OSM map tiles you see aren't created from your local database - they are just the standard map tiles.
+
+# Configuration
+
+After installing this software, you may need to carry out some [configuration steps](CONFIGURE.md), depending on your tasks.
--- a/README.md
+++ b/README.md
@ -1,136 +1,40 @@
-# Description
+# "The Rails Port"

-This is the Rails port, the [Ruby on Rails](http://rubyonrails.org/)
-application that powers [OpenStreetMap](http://www.openstreetmap.org).
+This is The Rails Port, the [Ruby on Rails](http://rubyonrails.org/)
+application that powers the [OpenStreetMap](http://www.openstreetmap.org) website and API.
+The software is also known as "openstreetmap-website".

-The Rails port provides almost all the services which are available 
-on the OpenStreetMap site, including:
+This repository consists of:

-* The web site itself, including the edit pages.
-* The editing [API](http://wiki.openstreetmap.org/wiki/API_v0.6).
-* Browse pages - a web front-end to the OpenStreetMap data.
-* The user system, including preferences, diary entries, friends and
-  user-to-user messaging.
-* GPX uploads, browsing and API.
+* The web site, including user accounts, diary entries, user-to-user messaging
+* The XML-based editing [API](http://wiki.openstreetmap.org/wiki/API_v0.6)
+* The integrated versions of the [Potlatch](http://wiki.openstreetmap.org/wiki/Potlatch_1), [Potlatch 2](http://wiki.openstreetmap.org/wiki/Potlatch_2) and [iD](http://wiki.openstreetmap.org/wiki/ID) editors
+* The Browse pages - a web front-end to the OpenStreetMap data
+* The GPX uploads, browsing and API.

-There are some non-Rails services which the site includes, for 
-example; tiles, geocoding, GPX file loading. There are also some
-utilities which provide other services on the OpenStreetMap site,
-or improve its function, but are not integrated with the Rails 
-port, for example; [Osmosis,](http://wiki.openstreetmap.org/wiki/Osmosis) 
-[CGImap.](https://github.com/zerebubuth/openstreetmap-cgimap)
+A fully-functional Rails Port installation depends on other services, including map tile
+servers and geocoding services, that are provided by other software. The default installation
+uses publically-available services to help with development and testing.

 # License

 This software is licensed under the [GNU General Public License 2.0](http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt),
-a copy of which can be found in the LICENSE file.
+a copy of which can be found in the [LICENSE](LICENSE) file.

-# Running it
+# Installation

-You can find documentation on [how to setup and
-run](http://wiki.openstreetmap.org/wiki/The_Rails_Port) the software
-on the OpenStreetMap wiki.
+The Rails Port is a Ruby on Rails application that uses PostgreSQL as its database, and has a large
+number of dependencies for installation. For full details please see [INSTALL.md](INSTALL.md)

-# Hacking it
+# Development

-The canonical Git repository for this software is hosted at
-[git.openstreetmap.org](http://git.openstreetmap.org/?p=rails.git),
-but much of the development is done on GitHub and for most people
-[this repository on Github](https://github.com/openstreetmap/openstreetmap-website)
-will be a better place to start.
+We're always keen to have more developers! Pull requests are very welcome.

-Anybody hacking on the code is welcome to join the
-[rails-dev](http://lists.openstreetmap.org/listinfo/rails-dev) mailing
-list where other people hacking on the code hang out and will be happy
-to help with any problems you may encounter. If you are looking for a
-project to help out with, please take a look at the list of 
-[Top Ten Tasks](http://wiki.openstreetmap.org/wiki/Top_Ten_Tasks) that
-EWG maintains on the wiki.
-
-There are also weekly IRC meetings, at 1800 GMT on Mondays in #osm-ewg on
-the OFTC network where questions can be asked and ideas discussed. For more 
-information, please see [the EWG page]
-(http://www.osmfoundation.org/wiki/Engineering_Working_Group#Meetings). You can
-join the channel using your favourite IRC client or [irc.openstreetmap.org](http://irc.openstreetmap.org/).
-
-## Rails
-
-If you're not already familiar with Ruby on Rails then it's probably
-worth having a look at [Rails Guides](http://guides.rubyonrails.org/) for an introduction.
-
-While working with Rails you will probably find the [API documentation](http://api.rubyonrails.org/)
-helpful as a reference.
-
-## Coding style
-
-When writing code it is generally a good idea to try and match your
-formatting to that of any existing code in the same file, or to other
-similar files if you are writing new code. Consistency of layout is
-far more important that the layout itself as it makes reading code
-much easier.
-
-One golden rule of formatting -- please don't use tabs in your code
-as they will cause the file to be formatted differently for different
-people depending on how they have their editor configured.
-
-## Testing
-
-Having a good suite of tests is very important to the stability and
-maintainability of any code base. The tests in the Rails port code are
-by no means complete, but they are extensive, and must continue to be
-so with any new functionality which is written. Tests are also useful
-in giving others confidence in the code you've written, and can
-greatly speed up the process of merging in new code.
-
-When hacking, you should:
-
-* Write new tests to cover the new functionality you've added.
-* Where appropriate, modify existing tests to reflect new or changed
-functionality.
-* Never comment out or remove a test just because it doesn't pass.
-
-## Comments
-
-Sometimes it's not apparent from the code itself what it does, or,
-more importantly, **why** it does that. Good comments help your fellow
-developers to read the code and satisfy themselves that it's doing the
-right thing.
-
-When hacking, you should:
-
-* Comment your code - don't go overboard, but explain the bits which
-might be difficult to understand what the code does, why it does it
-and why it should be the way it is.
-* Check existing comments to ensure that they are not misleading.
-
-## Committing
-
-When you submit patches, the project maintainer has to read them and
-understand them. This is difficult enough at the best of times, and
-misunderstanding patches can lead to them being more difficult to
-merge. To help with this, when submitting you should:
-
-* Split up large patches into smaller units of functionality.
-* Keep your commit messages relevant to the changes in each individual
-unit.
-
-When writing commit messages please try and stick to the same style as
-other commits, namely:
-
-* A one line summary, starting with a capital and with no full stop.
-* A blank line.
-* Full description, as proper sentences with capitals and full stops.
-
-For simple commits the one line summary is often enough and the body
-of the commit message can be left out.
-
-## Sending the patches
-
-If you have forked on GitHub then the best way to submit your patches is to
-push your changes back to GitHub and then send a "pull request" on GitHub.
-
-Otherwise you should either push your changes to a publicly visible git repository
-and send the details to the [rails-dev](http://lists.openstreetmap.org/listinfo/rails-dev)
-list or generate patches with `git format-patch` and send them to the
-[rails-dev](http://lists.openstreetmap.org/listinfo/rails-dev) list.
+* Bugs are recorded in the [issue tracker](https://github.com/openstreetmap/openstreetmap-website/issues).
+* Some bug reports are also found on the [OpenStreetMap trac](https://trac.openstreetmap.org/) system, in the "[website](https://trac.openstreetmap.org/query?status=new&status=assigned&status=reopened&component=website&order=priority)" and "[api](https://trac.openstreetmap.org/query?status=new&status=assigned&status=reopened&component=api&order=priority)" components
+* Translation is managed by [Translatewiki](https://translatewiki.net/wiki/Translating:OpenStreetMap)
+* There is a [rails-dev@openstreetmap.org](http://lists.openstreetmap.org/listinfo/rails-dev) mailing list for development discussion.
+* IRC - there is the #osm-dev channel on irc.oftc.net.
+* There are also weekly meetings of the OpenStreetMap Foundation Engineering Working Group (EWG) on Mondays at 1700 UTC on the #osm-ewg channel.

+More details on contributing to the code are in the [CONTRIBUTING.md](CONTRIBUTING.md) file.