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 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' and the files changed to be
owned by the user Apache runs as.
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 requires either the OpenLayers or Leaflet
Javascript library to be downloaded and installed and scripts are
provided for this.
cd /var/www/routino/www/openlayers
sh -x install.sh
cd /var/www/routino/www/leaflet
sh -x install.sh
To make full use of the location search feature on the Routino web page
you will need to install some extra perl packages.
apt-get install 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.
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. The files that need
editing are 'paths.pl' (to set the directory paths) and 'mapprops.js' (to
set the map properties).
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.
|
+ /openlayers/ <- A directory to hold the OpenLayers library
| (optional; leaflet can be used instead).
|
+ /leaflet/ <- A directory to hold the Leaflet library.
| (optional; 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 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/openlayers' is for the OpenLayers Javascript library
that can be downloaded from 'http://www.openlayers.org/'. (This version
of Routino has been tested with OpenLayers library versions 2.12 and
2.13.1). The file 'www/openlayers/OpenLayers.js' and the directories
'www/openlayers/img/' and 'www/openlayers/theme/' must all exist. There
is a script in the 'www/openlayers' directory that will automatically
download the files, create an optimised 'OpenLayers.js' and copy the
files to the required locations.
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 versions 0.7.1 and 0.7.2). The files
'www/leaflet/leaflet.js' and 'www/leaflet/leaflet.css' and the directory
'www/leaflet/images/' must all exist. 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 OpenLayers), 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.
--------
Copyright 2008-2015 Andrew M. Bishop.