trunk/doc/INSTALL.txt

                           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).

   ***********************************************************************
   *** 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 the OpenLayers Javascript to be
   downloaded and installed and a script is also provided for this.

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

   To make full use of the location search feature on the Routino web page
   you will need to install one extra perl package.

        apt-get install 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. The
   multi-threading can be disabled at compile time if required by
   commenting out a couple of lines in the file 'Makefile.conf'.

   To use the built-in file decompression functions the zlib (or libz) and
   bzip2 (or libbz2) development libraries are also required. (On Linux
   systems these might be in packages called libz-dev and libbz2-dev). If
   these are not available the function be disabled by commenting out a
   couple of lines in the file 'Makefile.conf'.

   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 additional Perl module "JSON::PP" must be installed.


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 scripts.
        |
        + /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.

   The directory 'www/openlayers' must be filled with 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.11 and 2.12). The files must be
   installed so that the file 'www/openlayers/OpenLayers.js' and the
   directories 'www/openlayers/img/', 'www/openlayers/theme/' all
   exist. There is a script in the directory that will automatically
   download the files, create an optimised "OpenLayers.js" and copy the
   files to the required locations.

   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 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 because of the way that the
   "AllowOverride" option works one of the configuration options has been
   commented out. This must be enabled 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 All
         Options +ExecCGI
     </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-2013 Andrew M. Bishop.
1	amb	429	Routino : Installation
2			======================
3	amb	152
4	amb	381
5	amb	1453	Quick Start Guide
6			-----------------
7
8			The instructions below are a complete list of the minimum required to
9			get Routino installed and running under Apache on Debian Linux (other
10			Linux versions will be similar).
11
12			***********************************************************************
13			* These instructions should not be considered as complete or a *
14			* secure installation for the reasons given in more detail below. *
15			***********************************************************************
16
17			The starting point for the installation is in the Routino source code
18			directory after it has been uncompressed. Most of the steps will need
19			to be run as the root user.
20
21			The first thing to do is to install the packages which are required for
22			compilation of Routino as described in the Pre-Requisites section
23			below.
24
25			apt-get install gcc make libc6-dev libz-dev libbz2-dev
26
27			After this the programs can be compiled:
28
29			make
30
31			The files for the web interface can now be copied to the web server
32			directory. On Debian this is '/var/www' and the files changed to be
33			owned by the user Apache runs as.
34
35			cp -a web /var/www/routino
36			chown -R www-data:www-data /var/www/routino
37
38			To be able to use Routino some data will need to be processed and a
39			script is provided for this. This will download the data for the UK
40			which may take a while and then process it.
41
42			cd /var/www/routino/data
43			sh -x create.sh
44
45			The routino web pages also requires the OpenLayers Javascript to be
46			downloaded and installed and a script is also provided for this.
47
48			cd /var/www/routino/www/openlayers
49			sh -x install.sh
50
51			To make full use of the location search feature on the Routino web page
52			you will need to install one extra perl package.
53
54			apt-get install libjson-pp-perl
55
56			Finally to make the web pages work you will need to add the extra lines
57			to the Apache configuration file as described in the Configuration of
58			Web Server section below. You don't have to use 'vi' and can use any
59			text editor.
60
61			vi /etc/apache2/sites-enabled/000-default
62			apache2ctl restart
63
64			Now everything should be set up and the web page should work if
65			accessed at 'http://localhost/routino/www/routino/router.html'.
66
67			When everything is working you should read the rest of this document
68			carefully and make the following changes:
69			* Download your choice of OSM data - edit the file data/create.sh and
70			run it again.
71			* Edit the www/routino/mapprops.js file to match the downloaded data
72			and personal map preferences.
73			* Move the files in the web server directory so that only the
74			contents of the www directory are accessible by the web server.
75			* Edit the file www/routino/paths.pl to reference the new file
76			locations.
77
78
79	amb	1269	Pre-Requisites
80			--------------
81
82			The programs are written in standard C language with minimal external
83			requirements so only a small set of development tools are required
84	amb	1343	(gcc, make). The compilation tools to use and the command line options
85			are defined in the file 'Makefile.conf'.
86	amb	1269
87			There is some support for multi-threading that uses pthreads and
88			additional development libraries for this may be required. The
89	amb	1343	multi-threading can be disabled at compile time if required by
90			commenting out a couple of lines in the file 'Makefile.conf'.
91	amb	1269
92			To use the built-in file decompression functions the zlib (or libz) and
93	amb	1425	bzip2 (or libbz2) development libraries are also required. (On Linux
94			systems these might be in packages called libz-dev and libbz2-dev). If
95			these are not available the function be disabled by commenting out a
96			couple of lines in the file 'Makefile.conf'.
97	amb	1269
98			To use the web page interface an http server is required. Instructions
99			below are for Apache but any server that supports CGIs should work.
100
101			The web pages use the Perl scripting language and a number of the
102			default Perl modules. To use the search function on the router web page
103			the additional Perl module "JSON::PP" must be installed.
104
105
106	amb	152	Compilation
107	amb	381	-----------
108	amb	152
109	amb	1269	To compile the programs just type 'make' at the top level of the source
110			tree.
111
112	amb	152	This program has been written to run on Linux, no cross-platform
113	amb	429	compatibility has been specifically included but on the other hand
114	amb	1269	other platforms have not knowingly been excluded either.
115	amb	152
116	amb	429	Any information on improving the compilation process on anything other
117	amb	1269	than x86 Linux is welcome.
118	amb	152
119
120	amb	429	Installation
121			------------
122	amb	152
123	amb	429	After compilation the executable files are copied into the directory
124			web/bin and the default XML configuration files are copied into the
125			directory web/data. This is in preparation for using the supplied
126			example web pages but is also a useful location to copy the files from
127			for normal use.
128	amb	191
129	amb	1274	The required executable files are 'planetsplitter', 'router' and
130			'filedumper' and the '*-slim' versions of the same files. They can be
131			copied to any location and need no special installation environment.
132	amb	1345	The 'filedumperx' executable is for debugging and not required.
133	amb	191
134	amb	1274	The configuration files are called 'profiles.xml', 'tagging.xml' and
135			'translations.xml'. The names of the configuration files can be
136			specified on the command line but by default are also looked for in the
137	amb	1453	directory that contains the routing database with these names.
138	amb	381
139	amb	191
140	amb	429	Example Web Page
141			----------------
142
143	amb	515	The directory 'web' contains a set of files that can be used to create
144			a working set of web pages with interfaces to the routing algorithm.
145	amb	191
146	amb	515	The files in the 'web' directory will require copying to a location
147			that is accessible by a web server. After copying the files some of
148			them need to be edited; search through the files for lines that contain
149			the words "EDIT THIS" and make appropriate edits. The files that need
150	amb	1269	editing are 'paths.pl' (to set the directory paths) and 'mapprops.js' (to
151	amb	998	set the map properties).
152	amb	191
153	amb	381
154	amb	191	Configuration of web files
155	amb	381	--------------------------
156	amb	191
157	amb	429	The assumption in this description is that the whole of the directory
158			called web is copied into a directory that is accessible by an Apache
159			web server.
160	amb	191
161			**************************************************************************
162			** This is not a secure configuration but an easy one to configure. **
163			** Only the directory 'www' should be accessible by the web server. **
164			** Do not use this configuration unmodified in a public web server. **
165			**************************************************************************
166
167			The directory structure is as follows:
168
169			web/
170			\|
171	amb	423	+ /bin/ <- The Routino executable files (when compiled).
172	amb	191	\|
173	amb	423	+ /data/ <- The Routino database and default configuration
174			\| files.
175	amb	191	\|
176			+ /results/ <- An empty directory to store the results.
177			\|
178			+ /www/ <- The files that must be available to the web
179			\| server are below this level.
180			\|
181			+ /openlayers/ <- A directory to hold the OpenLayers scripts.
182			\|
183			+ /routino/ <- The main HTML, Javascript, CSS and CGI files.
184	amb	515	\|
185			+ /documentation/ <- The HTML version of the Routino documentation.
186	amb	191
187	amb	429	The directory 'bin' will be filled by running the compilation process.
188			For a secure installation the 'bin' directory should be outside of the
189	amb	515	web server, the file 'www/routino/paths.pl' contains the path to the
190			'bin' directory.
191	amb	191
192	amb	423	The directory 'data' must contain the Routino database and is also the
193	amb	429	default location for the configuration files. The routing database is
194			created by downloading the OSM files for the region of interest and
195	amb	515	running the 'planetsplitter' program. There is a script in the
196			directory that will download the OSM files and create the required
197			database. The script should be edited to set the names of the files to
198			be downloaded. For a secure installation the 'data' directory should
199			be outside of the web server, the file 'www/routino/paths.pl' contains
200			the path to the 'data' directory.
201	amb	191
202	amb	515	The directory 'results' is a temporary directory that it used to hold
203			the GPX and text files generated by the Routino router. The directory
204			must be writable by the web server process since it is the CGI scripts
205			that are run by the web server that writes the results here. For a
206			secure installation the results directory should be outside of the web
207			server, the file 'www/routino/paths.pl' contains the path to the
208			results directory.
209	amb	191
210	amb	429	The directory 'www' and its sub-directories are the only ones that need
211			to be within the web server accessible directory.
212	amb	191
213	amb	429	The directory 'www/openlayers' must be filled with the openlayers
214			Javascript library that can be downloaded from
215	amb	515	http://www.openlayers.org/. (This version of Routino has been tested
216	amb	1269	with OpenLayers library versions 2.11 and 2.12). The files must be
217			installed so that the file 'www/openlayers/OpenLayers.js' and the
218			directories 'www/openlayers/img/', 'www/openlayers/theme/' all
219			exist. There is a script in the directory that will automatically
220			download the files, create an optimised "OpenLayers.js" and copy the
221			files to the required locations.
222	amb	191
223	amb	429	The directory 'www/routino' contains the main HTML, Javascript and CSS
224	amb	515	files as well as the CGI scripts that perform the server-side routing
225	amb	429	functions. The description below lists all of the files that contain
226			editable information.
227	amb	191
228	amb	429	paths.pl
229			This contains the names of the directories that contain the
230	amb	998	executable files, router database and temporary results; the
231			prefix for the routing database; and the names of the
232			executables.
233	amb	191
234	amb	1012	mapprops.js
235	amb	429	The parameters in this file control the boundary of the visible
236			map (defaults to UK), the minimum and maximum zoom levels
237	amb	1269	(defaults to between 4 and 15 inclusive), the source of map
238	amb	1334	tiles (defaults to the main OpenStreetMap tile server), the data
239	amb	1394	editing and browsing URLs (default to the OpenStreetMap website)
240			and the number of waypoints allowed (defaults to 9).
241	amb	191
242	amb	515	The directory www/routino/documentation contains the HTML version of
243			the Routino documentation.
244	amb	381
245	amb	901
246	amb	191	Configuration of web server
247
248	amb	515	The file 'www/routino/.htaccess' contains all of the Apache
249			configuration options that are required to get the example web pages
250			running. The only problem is that because of the way that the
251			"AllowOverride" option works one of the configuration options has been
252			commented out. This must be enabled in the main Apache server
253			configuration file.
254	amb	191
255	amb	1453	If you have copied the routino 'web' directory into '/var/www' and named
256			it 'routino' then the entry that you need in your Apache configuration
257			file is this one:
258	amb	1425
259	amb	1453	<Directory /var/www/routino>
260	amb	1425	AllowOverride All
261			Options +ExecCGI
262			</Directory>
263	amb	191
264	amb	1453	This can be placed anywhere between the <VirtualHost *:80> and
265			</VirtualHost> tags which should be at the start and end of the file.
266	amb	1425
267	amb	1453
268	amb	152	--------
269
270	amb	1425	Copyright 2008-2013 Andrew M. Bishop.