trunk/doc/INSTALL.txt

                           Routino : Installation
                           ======================


Compilation
-----------

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

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

   No external libraries are required and the programs are written in
   standard C language.

   To compile the programs just type 'make'.


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 executable files are called 'planetsplitter', 'router' and
   'filedumper' (also 'tagmodifier' for debugging tag modifications). They
   can be copied to any location and need no special installation
   environment.

   The default 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.


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 'router.js' and
   'visualiser.js' to limit the range of the visible map (latitude,
   longitude and zoom).


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 version 2.9.1). 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 and 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.

   router.pl
          This file contains the filename prefix for the routing database
          files (only needed if planetsplitter is run with the --prefix
          option).

   router.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) and the source of map
          tiles (defaults to the main OpenStreetMap tile server).

   visualiser.js
          The same parameters as in router.js are in this file.

   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.


--------

Copyright 2008-2010 Andrew M. Bishop.
1	Routino : Installation
2	======================
3
4
5	Compilation
6	-----------
7
8	This program has been written to run on Linux, no cross-platform
9	compatibility has been specifically included but on the other hand
10	nothing platform specific has been knowingly included either.
11
12	Any information on improving the compilation process on anything other
13	than 32-bit x86 Linux is welcome.
14
15	No external libraries are required and the programs are written in
16	standard C language.
17
18	To compile the programs just type 'make'.
19
20
21	Installation
22	------------
23
24	After compilation the executable files are copied into the directory
25	web/bin and the default XML configuration files are copied into the
26	directory web/data. This is in preparation for using the supplied
27	example web pages but is also a useful location to copy the files from
28	for normal use.
29
30	The executable files are called 'planetsplitter', 'router' and
31	'filedumper' (also 'tagmodifier' for debugging tag modifications). They
32	can be copied to any location and need no special installation
33	environment.
34
35	The default configuration files are called 'profiles.xml',
36	'tagging.xml' and 'translations.xml'. The names of the configuration
37	files can be specified on the command line but by default are also
38	looked for in the directory that contains the routing database.
39
40
41	Example Web Page
42	----------------
43
44	The directory 'web' contains a set of files that can be used to create
45	a working set of web pages with interfaces to the routing algorithm.
46
47	The files in the 'web' directory will require copying to a location
48	that is accessible by a web server. After copying the files some of
49	them need to be edited; search through the files for lines that contain
50	the words "EDIT THIS" and make appropriate edits. The files that need
51	editing are 'paths.pl' (to set the directory paths) and 'router.js' and
52	'visualiser.js' to limit the range of the visible map (latitude,
53	longitude and zoom).
54
55
56	Configuration of web files
57	--------------------------
58
59	The assumption in this description is that the whole of the directory
60	called web is copied into a directory that is accessible by an Apache
61	web server.
62
63	**************************************************************************
64	** This is not a secure configuration but an easy one to configure. **
65	** Only the directory 'www' should be accessible by the web server. **
66	** Do not use this configuration unmodified in a public web server. **
67	**************************************************************************
68
69	The directory structure is as follows:
70
71	web/
72	\|
73	+ /bin/ <- The Routino executable files (when compiled).
74	\|
75	+ /data/ <- The Routino database and default configuration
76	\| files.
77	\|
78	+ /results/ <- An empty directory to store the results.
79	\|
80	+ /www/ <- The files that must be available to the web
81	\| server are below this level.
82	\|
83	+ /openlayers/ <- A directory to hold the OpenLayers scripts.
84	\|
85	+ /routino/ <- The main HTML, Javascript, CSS and CGI files.
86	\|
87	+ /documentation/ <- The HTML version of the Routino documentation.
88
89
90	The directory 'bin' will be filled by running the compilation process.
91	For a secure installation the 'bin' directory should be outside of the
92	web server, the file 'www/routino/paths.pl' contains the path to the
93	'bin' directory.
94
95	The directory 'data' must contain the Routino database and is also the
96	default location for the configuration files. The routing database is
97	created by downloading the OSM files for the region of interest and
98	running the 'planetsplitter' program. There is a script in the
99	directory that will download the OSM files and create the required
100	database. The script should be edited to set the names of the files to
101	be downloaded. For a secure installation the 'data' directory should
102	be outside of the web server, the file 'www/routino/paths.pl' contains
103	the path to the 'data' directory.
104
105	The directory 'results' is a temporary directory that it used to hold
106	the GPX and text files generated by the Routino router. The directory
107	must be writable by the web server process since it is the CGI scripts
108	that are run by the web server that writes the results here. For a
109	secure installation the results directory should be outside of the web
110	server, the file 'www/routino/paths.pl' contains the path to the
111	results directory.
112
113	The directory 'www' and its sub-directories are the only ones that need
114	to be within the web server accessible directory.
115
116	The directory 'www/openlayers' must be filled with the openlayers
117	Javascript library that can be downloaded from
118	http://www.openlayers.org/. (This version of Routino has been tested
119	with OpenLayers library version 2.9.1). The files must be installed so
120	that the file 'www/openlayers/OpenLayers.js' and the directories
121	'www/openlayers/img/', 'www/openlayers/theme/' all exist. There is a
122	script in the directory that will automatically download and the files,
123	create an optimised "OpenLayers.js" and copy the files to the required
124	locations.
125
126	The directory 'www/routino' contains the main HTML, Javascript and CSS
127	files as well as the CGI scripts that perform the server-side routing
128	functions. The description below lists all of the files that contain
129	editable information.
130
131	paths.pl
132	This contains the names of the directories that contain the
133	executable files, router database and temporary results.
134
135	router.pl
136	This file contains the filename prefix for the routing database
137	files (only needed if planetsplitter is run with the --prefix
138	option).
139
140	router.js
141	The parameters in this file control the boundary of the visible
142	map (defaults to UK), the minimum and maximum zoom levels
143	(defaults to between 4 and 15 inclusive) and the source of map
144	tiles (defaults to the main OpenStreetMap tile server).
145
146	visualiser.js
147	The same parameters as in router.js are in this file.
148
149	The directory www/routino/documentation contains the HTML version of
150	the Routino documentation.
151
152	Configuration of web server
153	---------------------------
154
155	The file 'www/routino/.htaccess' contains all of the Apache
156	configuration options that are required to get the example web pages
157	running. The only problem is that because of the way that the
158	"AllowOverride" option works one of the configuration options has been
159	commented out. This must be enabled in the main Apache server
160	configuration file.
161
162
163	--------
164
165	Copyright 2008-2010 Andrew M. Bishop.