Openstreetmap-website

From OpenStreetMap Wiki
Revision as of 11:44, 29 October 2008 by Hubne (talk | contribs) (→‎Gems (libraries): +comment about rmagick case)
Jump to navigation Jump to search

The Rails port is the current version of OSM's server code - API, web front end and everything. If you have a Unix-like system (Linux, Mac OS X or a BSD) then you can install it on your own machine, so that you can make and test improvements to the code locally, then commit them to the OSM server. (This is not currently trivial for Windows users.)


Ruby on Rails

Ruby on Rails is a web development framework, written in Ruby. It is intended to make developing database driven web-based applications faster and more productive. For developers, this means less messing around configuring and more coding.

You should have some familiarity with Ruby and Model-View-Controller architectures before you start hacking on the OSM Rails port. Here are some resources that might help you:


Installing Rails

Prerequisites/Dependencies

The dependencies aren't particularly stretching for any linux distribution, and are roughly:

  • Ruby 1.8.4 or higher.
  • Ruby libxml bindings version 0.8.1 or higher.
  • Rails 2.0.2
  • MySQL 4.1.0 or higher

Some of the dependencies are covered in the platform-specific notes, whilst some are installed through the RubyGems system and are therefore platform-independant.

Platform-specific instructions

Gems (libraries)

When you have the dependencies and RubyGems installed, you need to install the following gems. Execute as root (sudo on Ubuntu/OS X) and answer yes to any questions. The specific versions of both Rails and composite_primary_keys are important! 

 # gem install -v=2.0.2 rails
 # gem install mysql
 # gem install libxml-ruby
 # gem install -v=0.9.93 composite_primary_keys
 # gem install RMagick
  • NB. try "rmagick" (lower case) if the RMagick gem is not found
(Hubne 11:44, 29 October 2008 (UTC))

Getting the OpenStreetMap code

If you want to download the entire OSM source tree - including all the editors, presentations and everything else, see Getting The Source. Otherwise you probably only want the rails_port bit of the repository. Pick a location where you want the code - your home directory is fine. 

 cd <your-base-path-for-source>
 svn co http://svn.openstreetmap.org/sites/rails_port

or, if you want to help with the current 0.6 API development, use 

 svn co http://svn.openstreetmap.org/sites/rails_port_branches/api06

Rails uses a preconfigured directory structure. Notable directories are: 

 db/  - Contains migrations and SQL to create databases (not the actual database)
 config/ - Application configuration files
 app/ - The application source code:
 app/controllers - The Controllers
 app/models - The Models
 app/views - The Views

Setting up an OSM database

If you want to do any work on the rails port, you'll need to have databases available. Rails uses three databases - one for development, one for testing, and one for production. The configuration for them is at config/database.yml - if you change the defaults make sure you adapt the statements below.

Creating a new database

You may create it with your preferred client or run this command on Unix systems: 

 $ mysql -u <uid> -p

(where <uid> is the username of an administrative user, e.g. root ) 

  create database openstreetmap default character set utf8;
  create database osm_test default character set utf8;
  create database osm default character set utf8;
  grant all privileges on openstreetmap.* to 'openstreetmap'@'localhost' identified by 'openstreetmap';
  grant all privileges on osm_test.* to 'osm_test'@'localhost' identified by 'osm_test';
  grant all privileges on osm.* to 'osm'@'localhost' identified by 'osm';
  flush privileges;
  exit

Now that mysql is all set up, we need to create the tables. Rails handles this by running a series of migrations (see db/migrate), which run quite fast on an empty db! For the development database, simply run 

 rake db:migrate

You don't need to worry about the test database, as "rake test" will take care of it automagically. To set up the production database (which you probably won't need), run: 

 env RAILS_ENV=production rake db:migrate


Populating the database

You can fill the api section of the database with data from planet files using Osmosis - information can be found on the Planet.osm page. This won't add any examples of diaries, gpx traces or fill the history tables. You might not need to do this if you're working on some other bit of the code.

Firing up Rails

The database is now configured and you are ready to roll with rails. Rails comes with its own webserver for testing, called WEBrick. On Unix-like systems as root do: 

 cd <path-to-osm-source>/sites/rails_port
 ruby script/server

In your favourite web-browser, go to: 

 http://localhost:3000/

You should see the OSM rails port. Congratulations!

Troubleshooting

Rails has its own log. To inspect the log, do this: 

 tail -f <path-to-osm-source>/sites/rails_port/log/development.log

If you have more problems, please ask on the dev mailing list (dev@openstreetmap.org) or on IRC. Here are some frequently encountered issues.

Missing subversion externals

If you hit the externals issues (http://svn.kylemaxwell.com/ is always down), then call 

 svn co --ignore-externals http://svn.openstreetmap.org/

and 

 svn update <path-to-osm-source>/sites/rails_port/vendor/plugins

to get some needed externals.

If getting the externals fails; here are some alternative ways to get them:

file_column external 

 #cd <path-to-osm-source>/sites/rails_port/vendor/plugins
 #svn co http://opensvn.csie.org/rails_file_column/plugins/file_column/trunk file_column

sql_session_store external 

 #cd <path-to-osm-source>/sites/rails_port/vendor/plugins
 #svn co svn://svn.usablelabs.com/kv/trunk/vendor/plugins/sql_session_store/ sql_session_store

Or download an archive of the files from http://dev.openstreetmap.org/~tomh/vendor.zip .

When running rake db:migrate

  • Running causes the error "undefined method 'file_column' for #<Class:0x########>."
    Ensure file_column has been pulled into vendor/plugins, if it svn externals are still broken, cd there and run:
svn co http://opensvn.csie.org/rails_file_column/plugins/file_column/trunk file_column

When booting Rails

  • If you get an error message about SQLSessionStore, the external dependencies (in /sites/rails_port/vendor/plugins) haven't been installed. Update your Subversion working copy and check that everything from other sites is being pulled in.
  • If you get an error message about "undefined method 'gem' for main::Object", see here.
  • If you get an error message about uninitialized constant RLIMIT_AS, comment out line 2 of sites/rails_port/config/initializers/limits.rb .
  • If you get errors about rspec (no such file to load -- spec/rake/spectask), then install rspec: ruby script/plugin install svn://rubyforge.org/var/svn/rspec/tags/CURRENT/rspec - see http://rspec.rubyforge.org/documentation/rails/install.html

When using the site

  • When you open localhost:3000, if you get a message like 'host myispname.co.uk is not allowed to connect to this database', that suggests you are trying to contact to the real live OSM database, rather than your own one. Edit sites/rails_port/config/database.yml, and change the IP addresses ('128....') to 'localhost'.
  • If the OSM page appears unstyled and incomplete, look at your browser/access logs - they may show requests for files like "localhost:3000/foo/bar/87623459". You can fix this by editing sites/rails/port/config/environments/development.rb and adding the line
 ENV['RAILS_ASSET_ID'] = ''

or by removing config/initializers/asset_tag_helper.rb from your local install.

  • If you want to create a new user, but haven't got an SMTP server set up to send out the confirmation mail, simply create the user, then edit the 'users' table and set active=1 in the relevant row.

Maintaining your installation

If your installation stops working for some reason:

  • The OSM database schema is changed periodically and you need to keep up with these improvements. Go to your rails_port directory and
 rake db:migrate

Getting GPX importing to work

You don't need the GPX import facility to work before using the rest of the Rails port. However, if you want to hack on this bit, too:

  • Make sure you have set the database settings for 'production' (config/database.yml) as well as 'development'
  • Make sure you have set your SMTP server in config/environment.rb (circa line 60)
  • Install the 'daemons' package: gem install daemons
  • Create directories at /home/osm/gpx and /home/osm/icons
  • Then start the import daemon running: script/daemons start

If you run into trouble, you can turn on logging by adding this line to lib/daemons/gpx_import_ctl

options[:log_output] = true

Logs will then be written in the log dir.

Installing the quadtile functions

This section is not essential and can be skipped by most users.

You can speed up the database loading by installing a specially-written MySQL function, providing quadtile support, before the database will run on your system. (This isn't essential.) The instructions in db/README for this explain how to do it. In brief: 

cd db/functions
make
  • Make sure the db/functions directory is on the MySQL server's library path and restart the MySQL server.
    • On Linux the easiest way to do this is to create /etc/ld.so.conf.d/osm.conf, and place the path to the db/functions directory in it and then run the ldconfig command as root.
    • On OS X: sudo ln -s /path_to_your_osm_install/sites/rails_port/db/functions/libmyosm.so /usr/local/lib/libmyosm.so
  • Log into MySQL (mysql -u <uid> -p openstreetmap, where <uid> is root or another administrative user)
 create function tile_for_point returns integer soname 'libmyosm.so';
 create function maptile_for_point returns integer soname 'libmyosm.so';
 exit

If mysql gives error messages similar to 

ERROR 1126 (HY000): Can't open shared library 'libmyosm.so' (errno: 2 libmyosm.so: cannot open shared object file: No such file or directory)

it is worth checking /var/log/kern.log to see if apparmor is blocking mysql's access to shared libraries in funny places. This will be the case if you're running on a default Ubuntu install, but may also apply to other distributions. To fix it, add the shared library with "mrix" permissions to the /etc/apparmor.d/usr.sbin.mysqld file.

Miscellanea

It is possible to produce diagrams of the rails port using railroad. More information is in The Rails Port/Railroad diagrams.

To generate the HTML documentation of the API/rails code, run the command rake doc:app

To generate test coverage stats, sudo gem install rcov. Then rcov -x gems test/*/*.rb in the rails_port directory.

Some information about testing.

Retrieved from "https://wiki.openstreetmap.org/w/index.php?title=Openstreetmap-website&oldid=170626"