Routino : Installation

Quick Start Guide

The instructions below are a complete list of the minimum required to get Routino installed and running under Apache on Debian Linux. Other Linux versions will be similar and other UNIX based systems will also be similar although may have distinct differences. There is some support in Routino for compiling on Microsoft Windows which has its own installation instructions.

These instructions should not be considered as complete or a secure installation for the reasons given in more detail in the Configuration of Web Files section below.

The starting point for the installation is in the Routino source code directory after it has been uncompressed. Most of the steps will need to be run as the root user.

The first thing to do is to install the packages which are required for compilation of Routino as described in the Pre-Requisites section below.

apt-get install gcc make libc6-dev libz-dev libbz2-dev

After this the programs can be compiled:

make

The files for the web interface can now be copied to the web server directory. On Debian this is /var/www (or more recently /var/www/html) and the files changed to be owned by the user Apache runs as. The instructions below are based on the assumption that the files are placed in /var/www, replace this with the chosen installation location if different.

cp -a web /var/www/routino
chown -R www-data:www-data /var/www/routino

To be able to use Routino some data will need to be processed and a script is provided for this. This will download the data for the UK which may take a while and then process it.

cd /var/www/routino/data
sh -x create.sh

The routino web pages also require either the OpenLayers (older version 2 or incompatible newer version) or Leaflet (recent version) Javascript library to be downloaded and installed; scripts are provided for this.

cd /var/www/routino/www/openlayers2
sh -x install.sh

cd /var/www/routino/www/openlayers
sh -x install.sh

cd /var/www/routino/www/leaflet
sh -x install.sh

To run the Perl scripts that are used on the Routino web page you will need to install some extra perl packages.

apt-get install libcgi-pm-perl libwww-perl liburi-perl libjson-pp-perl

Finally to make the web pages work you will need to add the extra lines to the Apache configuration file as described in the Configuration of Web Server section below. You don't have to use vi and can use any text editor.

vi /etc/apache2/sites-enabled/000-default
apache2ctl restart

Now everything should be set up and the web page should work if accessed at http://localhost/routino/www/routino/router.html.

When everything is working you should read the rest of this document carefully and make the following changes:

Download your choice of OSM data - edit the file data/create.sh and run it again.
Edit the www/routino/mapprops.js file to match the downloaded data and personal map preferences.
Move the files in the web server directory so that only the contents of the www directory are accessible by the web server.
Edit the file www/routino/paths.pl to reference the new file locations.

Pre-Requisites

The programs are written in standard C language with minimal external requirements so only a small set of development tools are required (gcc, make). The compilation tools to use and the command line options are defined in the file Makefile.conf.

There is some support for multi-threading that uses pthreads and additional development libraries for this may be required (on Linux this might be part of the standard C language development files). The multi-threading is enabled by default but can be disabled at compile time by commenting out two lines in the file Makefile.conf.

To use the built-in gzip file decompression function and to process all PBF format files the zlib (or libz) development library is required (on Linux this might be in a package called libz-dev). The gzip function is enabled by default but can be disabled by commenting out two lines in the file Makefile.conf.

To use the built-in bzip2 file decompression functions the bzip2 (or libbz2) development library is required (on Linux this might be in a package called libbz2-dev). The bzip2 function is enabled by default but can be disabled by commenting out two lines in the file Makefile.conf.

To use the built-in xz file decompression functions the liblzma development library is required (on Linux this might be in a package called liblzma-dev). The xz function is not enabled by default but can be enabled by uncommenting two lines in the file Makefile.conf.

To compile the source code from subversion requires the Perl Graphics::Magick module to generate the web page icons (on Linux this might be in a package called libgraphics-magick-perl). The released source code packages contains the icons so this package is not required for compilation.

To use the web page interface an http server is required. Instructions below are for Apache but any server that supports CGIs should work.

The web pages use the Perl scripting language and a number of the default Perl modules. To use the search function on the router web page the Perl module JSON::PP must be installed (on Linux this might be in a package called libjson-pp-perl if not part of the standard Perl installation).

Compilation

To compile the programs just type make at the top level of the source tree. There are a number of options that can be given when compiling to change the compilation options:

make CLANG=1: Compile with clang instead of gcc (default is CLANG=0).
make FASTMATHS=0: Compile without fast maths option (default is FASTMATHS=1).
make SANITIZE=1: Compile with gcc (or clang) sanitizer (default is SANITIZER=0).
make COVERAGE=1: Compile with gcc so that 'gcov' can be run to check code coverage (default is COVERAGE=0).
make PROFILE=1: Compile with gcc so that 'gprof' can be run to profile execution time (default is PROFILE=0).

This program has been written to run on Linux, no cross-platform compatibility has been specifically included but on the other hand other platforms have not knowingly been excluded either.

Any information on improving the compilation process on anything other than x86 Linux is welcome.

Installation

After compilation the executable files are copied into the directory web/bin and the default XML configuration files are copied into the directory web/data. This is in preparation for using the supplied example web pages but is also a useful location to copy the files from for normal use.

The required executable files are planetsplitter, router and filedumper and the *-slim versions of the same files. They can be copied to any location and need no special installation environment. The filedumperx executable is for debugging and not required.

The configuration files are called profiles.xml, tagging.xml and translations.xml. The names of the configuration files can be specified on the command line but by default are also looked for in the directory that contains the routing database with these names.

Example Web Page

The directory web contains a set of files that can be used to create a working set of web pages with interfaces to the routing algorithm.

The files in the web directory will require copying to a location that is accessible by a web server. After copying the files some of them need to be edited; search through the files for lines that contain the words "EDIT THIS" and make appropriate edits (more details below).

Configuration of Web Files

The assumption in this description is that the whole of the directory called web is copied into a directory that is accessible by an Apache web server.

This is not a secure configuration but an easy one to configure.
Only the directory www should be accessible by the web server. Do not use this configuration unmodified in a public web server.

The directory structure is as follows:

   web/
    |
    + /bin/                    <- The Routino executable files (when compiled).
    |
    + /data/                   <- The Routino database and default configuration
    |                             files.
    |
    + /results/                <- An empty directory to store the results.
    |
    + /www/                    <- The files that must be available to the web
        |                         server are below this level.
        |
        + /openlayers2/        <- A directory to hold the older OpenLayers v2
        |                         library (optional; newer openlayers or leaflet
        |                         can be used instead).
        |
        + /openlayers/         <- A directory to hold the newer OpenLayers
        |                         library (optional; older openlayers v2 or
        |                         leaflet can be used instead).
        |
        + /leaflet/            <- A directory to hold the Leaflet library.
        |                         (optional; older openlayers v2 or newer
        |                          openlayers can be used instead).
        |
        + /routino/            <- The main HTML, Javascript, CSS and CGI files.
            |
            + /documentation/  <- The HTML version of the Routino documentation.

The directory bin will be filled by running the compilation process. For a secure installation the bin directory should be outside of the web server, the file www/routino/paths.pl contains the path to the bin directory.

The directory data must contain the Routino database and is also the default location for the configuration files. The routing database is created by downloading the OSM files for the region of interest and running the planetsplitter program. There is a script in the directory that will download the OSM files and create the required database. The script should be edited to set the names of the files to be downloaded. For a secure installation the data directory should be outside of the web server, the file www/routino/paths.pl contains the path to the data directory.

The directory results is a temporary directory that it used to hold the GPX and text files generated by the Routino router. The directory must be writable by the web server process since it is the CGI scripts that are run by the web server that writes the results here. For a secure installation the results directory should be outside of the web server, the file www/routino/paths.pl contains the path to the results directory.

The directory www and its sub-directories are the only ones that need to be within the web server accessible directory.

A Javascript map drawing library is required and either the older OpenLayers version 2, newer Openlayers or Leaflet can be used. The library is loaded dynamically when the HTML is opened based on the value that is selected in mapprops.js.

The directory www/openlayers2 is for the older OpenLayers version 2 Javascript library that can be downloaded from http://www.openlayers.org/two/. (This version of Routino has been tested with OpenLayers library version 2.13.1). There is a script in the www/openlayers2 directory that will automatically download the files, create an optimised OpenLayers.js and copy the files to the required locations.

The directory www/openlayers is for the newer version of the OpenLayers Javascript library that can be downloaded from http://www.openlayers.org/. (This version of Routino has been tested with OpenLayers library version 6.4.3). There is a script in the www/openlayers directory that will automatically download the files.

The directory www/leaflet is for the Leaflet Javascript library that can be downloaded from http://leafletjs.com/. (This version of Routino has been tested with Leaflet library version 1.7.1). There is a script in the www/leaflet directory that will automatically download the files.

The directory www/routino contains the main HTML, Javascript and CSS files as well as the CGI scripts that perform the server-side routing functions. The description below lists all of the files that contain editable information.

paths.pl: This contains the names of the directories that contain the executable files, router database and temporary results; the prefix for the routing database; and the names of the executables.
mapprops.js: The parameters in this file control the Javascript map library (defaults to Leaflet), the boundary of the visible map (defaults to UK), the minimum and maximum zoom levels (defaults to between 4 and 15 inclusive), the source of map tiles (defaults to the main OpenStreetMap tile server), the data editing and browsing URLs (default to the OpenStreetMap website) and the number of waypoints allowed (defaults to 9).

The directory www/routino/documentation contains the HTML version of the Routino documentation.

Configuration of Web Server

The file www/routino/.htaccess contains all of the Apache configuration options that are required to get the example web pages running. The only problem is that some of the configuration options in that file will not work unless they are allowed by the AllowOverride option in the main Apache server configuration file.

If you have copied the routino web directory into /var/www and named it routino then the entry that you need in your Apache configuration file is this one:

     <Directory /var/www/routino>
         AllowOverride Options=MultiViews,ExecCGI FileInfo Limit
     </Directory>

This can be placed anywhere between the <VirtualHost *:80> and </VirtualHost> tags which should be at the start and end of the file.