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 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' (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/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.conf
        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. 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.
        |
        + /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.


--------

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