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 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 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-2014 Andrew M. Bishop.
1	Routino : Installation
2	======================
3
4
5	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 either the OpenLayers or Leaflet
46	Javascript library to be downloaded and installed and scripts are
47	provided for this.
48
49	cd /var/www/routino/www/openlayers
50	sh -x install.sh
51
52	cd /var/www/routino/www/leaflet
53	sh -x install.sh
54
55	To make full use of the location search feature on the Routino web page
56	you will need to install some extra perl packages.
57
58	apt-get install libwww-perl liburi-perl libjson-pp-perl
59
60	Finally to make the web pages work you will need to add the extra lines
61	to the Apache configuration file as described in the Configuration of
62	Web Server section below. You don't have to use 'vi' and can use any
63	text editor.
64
65	vi /etc/apache2/sites-enabled/000-default
66	apache2ctl restart
67
68	Now everything should be set up and the web page should work if
69	accessed at 'http://localhost/routino/www/routino/router.html'.
70
71	When everything is working you should read the rest of this document
72	carefully and make the following changes:
73	* Download your choice of OSM data - edit the file data/create.sh and
74	run it again.
75	* Edit the www/routino/mapprops.js file to match the downloaded data
76	and personal map preferences.
77	* Move the files in the web server directory so that only the
78	contents of the www directory are accessible by the web server.
79	* Edit the file www/routino/paths.pl to reference the new file
80	locations.
81
82
83	Pre-Requisites
84	--------------
85
86	The programs are written in standard C language with minimal external
87	requirements so only a small set of development tools are required
88	(gcc, make). The compilation tools to use and the command line options
89	are defined in the file 'Makefile.conf'.
90
91	There is some support for multi-threading that uses pthreads and
92	additional development libraries for this may be required (on Linux
93	this might be part of the standard C language development files). The
94	multi-threading is enabled by default but can be disabled at compile
95	time by commenting out two lines in the file 'Makefile.conf'.
96
97	To use the built-in gzip file decompression function and to process all
98	PBF format files the zlib (or libz) development library is required (on
99	Linux this might be in a package called libz-dev). The gzip function is
100	enabled by default but can be disabled by commenting out two lines in
101	the file 'Makefile.conf'.
102
103	To use the built-in bzip2 file decompression functions the bzip2 (or
104	libbz2) development library is required (on Linux this might be in a
105	package called libbz2-dev). The bzip2 function is enabled by default
106	but can be disabled by commenting out two lines in the file
107	'Makefile.conf'.
108
109	To use the built-in xz file decompression functions the liblzma
110	development library is required (on Linux this might be in a package
111	called liblzma-dev). The xz function is not enabled by default but can
112	be enabled by uncommenting two lines in the file 'Makefile.conf'.
113
114	To compile the source code from subversion requires the Perl
115	Graphics::Magick module to generate the web page icons (on Linux this
116	might be in a package called libgraphics-magick-perl). The released
117	source code packages contains the icons so this package is not required
118	for compilation.
119
120	To use the web page interface an http server is required. Instructions
121	below are for Apache but any server that supports CGIs should work.
122
123	The web pages use the Perl scripting language and a number of the
124	default Perl modules. To use the search function on the router web page
125	the Perl module JSON::PP must be installed (on Linux this might be in a
126	package called libjson-pp-perl if not part of the standard Perl
127	installation).
128
129	Compilation
130	-----------
131
132	To compile the programs just type 'make' at the top level of the source
133	tree.
134
135	This program has been written to run on Linux, no cross-platform
136	compatibility has been specifically included but on the other hand
137	other platforms have not knowingly been excluded either.
138
139	Any information on improving the compilation process on anything other
140	than x86 Linux is welcome.
141
142
143	Installation
144	------------
145
146	After compilation the executable files are copied into the directory
147	web/bin and the default XML configuration files are copied into the
148	directory web/data. This is in preparation for using the supplied
149	example web pages but is also a useful location to copy the files from
150	for normal use.
151
152	The required executable files are 'planetsplitter', 'router' and
153	'filedumper' and the '*-slim' versions of the same files. They can be
154	copied to any location and need no special installation environment.
155	The 'filedumperx' executable is for debugging and not required.
156
157	The configuration files are called 'profiles.xml', 'tagging.xml' and
158	'translations.xml'. The names of the configuration files can be
159	specified on the command line but by default are also looked for in the
160	directory that contains the routing database with these names.
161
162
163	Example Web Page
164	----------------
165
166	The directory 'web' contains a set of files that can be used to create
167	a working set of web pages with interfaces to the routing algorithm.
168
169	The files in the 'web' directory will require copying to a location
170	that is accessible by a web server. After copying the files some of
171	them need to be edited; search through the files for lines that contain
172	the words "EDIT THIS" and make appropriate edits. The files that need
173	editing are 'paths.pl' (to set the directory paths) and 'mapprops.js' (to
174	set the map properties).
175
176
177	Configuration of web files
178	--------------------------
179
180	The assumption in this description is that the whole of the directory
181	called web is copied into a directory that is accessible by an Apache
182	web server.
183
184	**************************************************************************
185	** This is not a secure configuration but an easy one to configure. **
186	** Only the directory 'www' should be accessible by the web server. **
187	** Do not use this configuration unmodified in a public web server. **
188	**************************************************************************
189
190	The directory structure is as follows:
191
192	web/
193	\|
194	+ /bin/ <- The Routino executable files (when compiled).
195	\|
196	+ /data/ <- The Routino database and default configuration
197	\| files.
198	\|
199	+ /results/ <- An empty directory to store the results.
200	\|
201	+ /www/ <- The files that must be available to the web
202	\| server are below this level.
203	\|
204	+ /openlayers/ <- A directory to hold the OpenLayers library
205	\| (optional; leaflet can be used instead).
206	\|
207	+ /leaflet/ <- A directory to hold the Leaflet library.
208	\| (optional; openlayers can be used instead).
209	\|
210	+ /routino/ <- The main HTML, Javascript, CSS and CGI files.
211	\|
212	+ /documentation/ <- The HTML version of the Routino documentation.
213
214	The directory 'bin' will be filled by running the compilation process.
215	For a secure installation the 'bin' directory should be outside of the
216	web server, the file 'www/routino/paths.pl' contains the path to the
217	'bin' directory.
218
219	The directory 'data' must contain the Routino database and is also the
220	default location for the configuration files. The routing database is
221	created by downloading the OSM files for the region of interest and
222	running the 'planetsplitter' program. There is a script in the
223	directory that will download the OSM files and create the required
224	database. The script should be edited to set the names of the files to
225	be downloaded. For a secure installation the 'data' directory should
226	be outside of the web server, the file 'www/routino/paths.pl' contains
227	the path to the 'data' directory.
228
229	The directory 'results' is a temporary directory that it used to hold
230	the GPX and text files generated by the Routino router. The directory
231	must be writable by the web server process since it is the CGI scripts
232	that are run by the web server that writes the results here. For a
233	secure installation the results directory should be outside of the web
234	server, the file 'www/routino/paths.pl' contains the path to the
235	results directory.
236
237	The directory 'www' and its sub-directories are the only ones that need
238	to be within the web server accessible directory.
239
240	A Javascript map drawing library is required and either OpenLayers or
241	Leaflet can be used. The library is loaded dynamically when the HTML is
242	opened based on the value that is selected in 'mapprops.js'.
243
244	The directory 'www/openlayers' is for the OpenLayers Javascript library
245	that can be downloaded from 'http://www.openlayers.org/'. (This version
246	of Routino has been tested with OpenLayers library versions 2.12 and
247	2.13.1). The file 'www/openlayers/OpenLayers.js' and the directories
248	'www/openlayers/img/' and 'www/openlayers/theme/' must all exist. There
249	is a script in the 'www/openlayers' directory that will automatically
250	download the files, create an optimised 'OpenLayers.js' and copy the
251	files to the required locations.
252
253	The directory 'www/leaflet' is for the Leaflet Javascript library that
254	can be downloaded from 'http://leafletjs.com/'. (This version of Routino
255	has been tested with Leaflet library versions 0.7.1 and 0.7.2). The files
256	'www/leaflet/leaflet.js' and 'www/leaflet/leaflet.css' and the directory
257	'www/leaflet/images/' must all exist. There is a script in the
258	'www/leaflet' directory that will automatically download the files.
259
260	The directory 'www/routino' contains the main HTML, Javascript and CSS
261	files as well as the CGI scripts that perform the server-side routing
262	functions. The description below lists all of the files that contain
263	editable information.
264
265	paths.pl
266	This contains the names of the directories that contain the
267	executable files, router database and temporary results; the
268	prefix for the routing database; and the names of the
269	executables.
270
271	mapprops.js
272	The parameters in this file control the Javascript map library
273	(defaults to OpenLayers), the boundary of the visible map
274	(defaults to UK), the minimum and maximum zoom levels (defaults
275	to between 4 and 15 inclusive), the source of map tiles
276	(defaults to the main OpenStreetMap tile server), the data
277	editing and browsing URLs (default to the OpenStreetMap website)
278	and the number of waypoints allowed (defaults to 9).
279
280	The directory www/routino/documentation contains the HTML version of
281	the Routino documentation.
282
283
284	Configuration of Web Server
285	---------------------------
286
287	The file 'www/routino/.htaccess' contains all of the Apache
288	configuration options that are required to get the example web pages
289	running. The only problem is that because of the way that the
290	"AllowOverride" option works one of the configuration options has been
291	commented out. This must be enabled in the main Apache server
292	configuration file.
293
294	If you have copied the routino 'web' directory into '/var/www' and named
295	it 'routino' then the entry that you need in your Apache configuration
296	file is this one:
297
298	<Directory /var/www/routino>
299	AllowOverride All
300	Options +ExecCGI
301	</Directory>
302
303	This can be placed anywhere between the <VirtualHost *:80> and
304	</VirtualHost> tags which should be at the start and end of the file.
305
306
307	--------
308
309	Copyright 2008-2014 Andrew M. Bishop.