= Rendering OSM data with MapServer on Ubuntu 10.10 =

This page provides step by step instructions to setup a Ubuntu 10.10 LTS server from scratch to render OSM data with MapServer 6.x.

The following instructions assume that we start with a brand new Ubuntu 10.10 server with Apache installed but none of the MapServer related packages installed.

The setup will include:

 * MapServer 6.x (from the UbuntuGIS repository)
 * PostgreSQL/PostGIS (from the UbuntuGIS repository)
 * OSM data to be downloaded from http://download.geofabrik.de/osm/
 * Use of "imposm" to load the data in PostGIS: http://imposm.org/
 * Map configured in EPSG:900913 projection, with data loaded for the state of Alabama only, and using a Google-like style
 * MapFile generated using "mapserver-utils": http://code.google.com/p/mapserver-utils/
 * Tile caching using Mod-Geocache (to be renamed MapCache):  http://mod-geocache.googlecode.com/

== Create work directory ==

 * All the steps that follow assume that the data and mapfiles will be installed in a directory called "osm-demo" in your home directory
 * Commands:
{{{
  mkdir ~/osm-demo
  cd ~/osm-demo/
}}}

== Install UbuntuGIS MapServer and PostGIS packages ==

 * Relevant docs:  http://trac.osgeo.org/ubuntugis/wiki/UbuntuGISRepository
 * At the time of this writing, the current version of MapServer is 6.0.1
 * Commands:
{{{
  sudo apt-get install python-software-properties
  sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
  sudo apt-get update
  sudo apt-get install cgi-mapserver mapserver-bin

  sudo apt-get install postgresql
  sudo apt-get install postgis postgresql-8.4-postgis
}}}
 * Install other non-GIS packages that will be required later on:
{{{
  sudo apt-get install mercurial subversion
  sudo apt-get install zip unzip
}}}

== Download OSM data ==

 * You can download data for your region of interest from http://download.geofabrik.de/osm/. The rest of these instructions assume that we work with the data for the state of Alabama.
 * Commands:
{{{
  cd ~/osm-demo/
  wget http://download.geofabrik.de/osm/north-america/us/alabama.osm.pbf
}}}

== Install imposm, using virtualenv ==

 * Relevant docs: http://imposm.org/docs/imposm/latest/install.html
 * Commands:
{{{
  cd ~/osm-demo/
  sudo apt-get install build-essential python-dev protobuf-compiler \
                      libprotobuf-dev libtokyocabinet-dev python-psycopg2 \
                      libgeos-c1

  sudo apt-get install python-virtualenv
  virtualenv venv
}}}
 * Install shapely speedups:
{{{
  sudo apt-get install libgeos-dev
  venv/bin/pip install https://github.com/olt/shapely_speedups/tarball/master
}}}
 * IMPORTANT: We will use a custom branch of imposm created by tbonfort that creates additional generalized tables for use with mapserver-utils:
{{{
  hg clone https://bitbucket.org/tbonfort/imposm-tbonfort
  vi imposm-tbonfort/imposm/defaultmapping.py
... change proj to epsg:900913 (it is set to epsg:4326 bu default)
}}}
 * If we wanted to use the release version of imposm instead then we'd have run the following command, BUT WE DO NOT WANT THAT... this command included here only for reference:
{{{
  # Do not run this command unless you plan to use the release version of imposm
  #venv/bin/pip install imposm
}}}

 * TODO: Verify if released version of imposm includes all required tables and views, and when it does update these instructions to avoid using the custom branch.

== Create database ==

 * Relevant docs: http://imposm.org/docs/imposm/latest/tutorial.html
 * Commands:
{{{
  ~/osm-demo/venv/bin/python imposm-tbonfort/imposm/psqldb.py > create-db.sh
  vi ./create-db.sh # cross check if all path are set
... edit the following lines:
-------------------8<--------------
psql -d osm -f /usr/share/postgresql/8.4/contrib/postgis-1.5/postgis.sql             # <- CHANGE THIS PATH
psql -d osm -f /usr/share/postgresql/8.4/contrib/postgis-1.5/spatial_ref_sys.sql     # <- CHANGE THIS PATH
------------------->8--------------

  sudo su postgres
  sh ./create-db.sh
  /etc/init.d/postgresql-8.4 restart
  exit
}}}
 * Note: If we were using the released version of imposm then the first command would have been:
{{{
  venv/bin/imposm-psqldb > create-db.sh
}}}


== Load data using imposm ==

 * Relevant docs: http://imposm.org/docs/imposm/latest/tutorial.html
 * Commands:
{{{
  cd ~/osm-demo/
  ~/osm-demo/venv/bin/python imposm-tbonfort/imposm/app.py --read alabama.osm.pbf
  ~/osm-demo/venv/bin/python imposm-tbonfort/imposm/app.py  --write --database osm --host localhost --user osm
  ~/osm-demo/venv/bin/python imposm-tbonfort/imposm/app.py  --optimize -d osm
}}}
 * Note: multiple .osm.pbf files can be loaded in separate commands using the --merge-cache argument.

== Install mapserver-utils mapfile generator ==

 * Website: http://code.google.com/p/mapserver-utils/
 * Check out the 'imposm-branch' from SVN:
{{{
  cd ~/osm-demo/
  svn checkout http://mapserver-utils.googlecode.com/svn/branches/imposm-branch/ mapserver-utils-svn-imposm
  cd mapserver-utils-svn-imposm
}}}
 * Update mapserver-utils's osmbase.map and Makefile as follows:
{{{
  vi osm-base.map
-------------------8<------------------------
  WEB
...
    IMAGEPATH "/tmp/ms_tmp/"
    IMAGEURL "/ms_tmp/"
 END
...
-------------------->8-----------------------

  vi Makefile
-------------------8<------------------------
OSM_SRID=900913
OSM_UNITS=meters
OSM_EXTENT=-20000000 -20000000 20000000 20000000
...
STYLE=google
-------------------->8-----------------------
}}}
 * Create MapServer temp dirs (required by mapserv CGI for testing with openlayers template)
{{{
  mkdir /tmp/ms_tmp
  chmod 777 /tmp/ms_tmp
}}}

 * Execute the mapserver-utils makefile to generate the mapfile. Note that the first time you run 'make' several large files will be downloaded (country boundaries, etc.). This will happen only the first time.
{{{
  cd ~/osm-demo/mapserver-utils-svn-imposm
  make
}}}
 * The 'make' command will have generated a osm-google.map based on the parameters in the generate_style.py script. 
 * More information about tweaking the map styles is available at http://code.google.com/p/mapserver-utils/wiki/TweakingMapStylesImposm

 * Access your map online using MapServer's built-in template=openlayers mode:
{{{
http://yourserver.tld/cgi-bin/mapserv?map=/path/to/osm-demo/mapserver-utils-svn-imposm/osm-google.map&mode=browse&template=openlayers&layers=all
}}}

== Setup Mod-Geocache ==
 * Relevant docs: http://mod-geocache.googlecode.com/svn/trunk/INSTALL
 * Required packages:
{{{
  sudo apt-get install autoconf
  sudo apt-get install apache2-dev
  sudo apt-get install libcairo2-dev
}}}
 * Checkout and build source:
{{{
  mkdir ~/src
  cd ~/src
  svn checkout http://mod-geocache.googlecode.com/svn/trunk/ mod-geocache-svn-ro
  cd mod-geocache-svn-ro/
  ./configure
  make

  sudo make install-module
  sudo apache2ctl restart  
}}}
 * Create our own geocache-osm.xml based on docs in sample geocache.xml (http://mod-geocache.googlecode.com/svn/trunk/geocache.xml) or in pretty print at http://code.google.com/p/mod-geocache/source/browse/trunk/geocache.xml
{{{
  mkdir ~/osm-demo/geocache
  cp ~/src/mod-geocache-svn-ro/geocache.xml ~/osm-demo/geocache/geocache-osm.xml
  vi ~/osm-demo/geocache/geocache-osm.xml
... make required changes to template to make it work with our installation...

  sudo apache2ctl restart
}}}

 * Ready to test server, see URL docs at http://code.google.com/p/mod-geocache/wiki/RequestingTilesFromService#TMS_service
 * TMS service available at http://yourserver.tld/geocache/tms/1.0.0/
   * Sample tile:  http://yourserver.tld/geocache/tms/1.0.0/osm@g/3/2/5.png
   * Sample OpenLayers app to test TMS: http://openlayers.org/dev/examples/tms.html

 * You can optionally run the cache seeder, see: http://code.google.com/p/mod-geocache/wiki/UsingTheSeeder