doc/html/installation.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML>

<!--
 Routino documentation - installation

 Part of the Routino routing software.

 This file Copyright 2008-2010 Andrew M. Bishop

 This program is free software: you can redistribute it and/or modify
 it under the terms of the GNU Affero General Public License as published by
 the Free Software Foundation, either version 3 of the License, or
 (at your option) any later version.

 This program is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU Affero General Public License for more details.

 You should have received a copy of the GNU Affero General Public License
 along with this program.  If not, see http://www.gnu.org/licenses/.
-->

<HEAD>
<TITLE>Routino : Installation</TITLE>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<LINK href="style.css" type="text/css" rel="stylesheet">
</HEAD>

<BODY>

<!-- Header Start -->

<div class="header" align="center">

<h1>Routino : Installation</h1>

<hr>
</div>

<!-- Header End -->

<!-- Content Start -->

<div class="content">


<h2><a name="H_1_1"></a>Compilation</h2>

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.

<p>

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

<p>

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

<p>

To compile the programs just type 'make'.


<h2><a name="H_1_2"></a>Installation</h2>

After compilation the executable files are copied into the directory
<tt>web/bin</tt> and the default XML configuration files are copied into the
directory <tt>web/data</tt>.  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.

<p>

The executable files are called <tt>planetsplitter</tt>, <tt>router</tt> and
<tt>filedumper</tt> (also <tt>tagmodifier</tt> for debugging tag modifications).
They can be copied to any location and need no special installation environment.

<p>

The default configuration files are called <tt>profiles.xml</tt>,
<tt>tagging.xml</tt> and <tt>translations.xml</tt>.  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.


<h2><a name="H_1_3"></a>Example Web Page</h2>

The directory <tt>web</tt> contains a set of files that can be used to create a
working set of web pages with interfaces to the routing algorithm.

<p>

The files in the <tt>web</tt> 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 <tt>paths.pl</tt>
(to set the directory paths) and <tt>router.js</tt> and <tt>visualiser.js</tt>
to limit the range of the visible map (latitude, longitude and zoom).


<h3><a name="H_1_3_1"></a>Configuration of web files</h3>

The assumption in this description is that the whole of the directory called
<tt>web</tt> is copied into a directory that is accessible by an Apache web
server.

<p>

<em>This is not a secure configuration but an easy one to configure.</em>
<br>
<em>Only the directory <tt>www</tt> should be accessible by the web server.</em>
<br>
<em>Do not use this configuration unmodified in a public web server.</em>

<p>

The directory structure is as follows:

<pre>
   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.
</pre>

The directory <tt>bin</tt> will be filled by running the compilation process.
For a secure installation the <tt>bin</tt> directory should be outside of the
web server, the file <tt>www/routino/paths.pl</tt> contains the path to
the <tt>bin</tt> directory.

<p>

The directory <tt>data</tt> 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 <tt>data</tt> directory should be outside of the web server, the
file <tt>www/routino/paths.pl</tt> contains the path to the <tt>data</tt>
directory.

<p>

The directory <tt>results</tt> 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 <tt>results</tt> directory should be outside of the web server, the file
<tt>www/routino/paths.pl</tt> contains the path to the <tt>results</tt> directory.

<p>

The directory <tt>www</tt> and its sub-directories are the only ones that need
to be within the web server accessible directory.

<p>

The directory <tt>www/openlayers</tt> 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 <tt>www/openlayers/OpenLayers.js</tt>
and the directories <tt>www/openlayers/img/</tt>, <tt>www/openlayers/theme/</tt>
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.

<p>

The directory <tt>www/routino</tt> 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.

<dl>
  <dt>paths.pl
  <dd>This contains the names of the directories that contain the executable
      files, router database and temporary results.
  <dt>router.pl
  <dd>This file contains the filename prefix for the routing database files
      (only needed if planetsplitter is run with the --prefix option).
  <dt>router.js
  <dd>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).
  <dt>visualiser.js
  <dd>The same parameters as in router.js are in this file.
</dl>

<p>

The directory <tt>www/routino/documentation</tt> contains the HTML version of
the Routino documentation.


<h3><a name="H_1_3_2"></a>Configuration of web server</h3>

The file <tt>www/routino/.htaccess</tt> 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 <tt>AllowOverride</tt> option works
one of the configuration options has been commented out.  This must be enabled
in the main Apache server configuration file.


</div>

<!-- Content End -->

<!-- Footer Start -->

<div class="footer" align="center">
<hr>

<address>
&copy; Andrew M. Bishop = &lt;amb "at" gedanken.demon.co.uk&gt;
</address>

</div>

<!-- Footer End -->

</BODY>

</HTML>
1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2	<HTML>
3
4	<!--
5	Routino documentation - installation
6
7	Part of the Routino routing software.
8
9	This file Copyright 2008-2010 Andrew M. Bishop
10
11	This program is free software: you can redistribute it and/or modify
12	it under the terms of the GNU Affero General Public License as published by
13	the Free Software Foundation, either version 3 of the License, or
14	(at your option) any later version.
15
16	This program is distributed in the hope that it will be useful,
17	but WITHOUT ANY WARRANTY; without even the implied warranty of
18	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19	GNU Affero General Public License for more details.
20
21	You should have received a copy of the GNU Affero General Public License
22	along with this program. If not, see http://www.gnu.org/licenses/.
23	-->
24
25	<HEAD>
26	<TITLE>Routino : Installation</TITLE>
27	<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
28	<LINK href="style.css" type="text/css" rel="stylesheet">
29	</HEAD>
30
31	<BODY>
32
33	<!-- Header Start -->
34
35	<div class="header" align="center">
36
37	<h1>Routino : Installation</h1>
38
39	<hr>
40	</div>
41
42	<!-- Header End -->
43
44	<!-- Content Start -->
45
46	<div class="content">
47
48
49	<h2><a name="H_1_1"></a>Compilation</h2>
50
51	This program has been written to run on Linux, no cross-platform compatibility
52	has been specifically included but on the other hand nothing platform specific
53	has been knowingly included either.
54
55	<p>
56
57	Any information on improving the compilation process on anything other than
58	32-bit x86 Linux is welcome.
59
60	<p>
61
62	No external libraries are required and the programs are written in standard C
63	language.
64
65	<p>
66
67	To compile the programs just type 'make'.
68
69
70	<h2><a name="H_1_2"></a>Installation</h2>
71
72	After compilation the executable files are copied into the directory
73	<tt>web/bin</tt> and the default XML configuration files are copied into the
74	directory <tt>web/data</tt>. This is in preparation for using the supplied
75	example web pages but is also a useful location to copy the files from for
76	normal use.
77
78	<p>
79
80	The executable files are called <tt>planetsplitter</tt>, <tt>router</tt> and
81	<tt>filedumper</tt> (also <tt>tagmodifier</tt> for debugging tag modifications).
82	They can be copied to any location and need no special installation environment.
83
84	<p>
85
86	The default configuration files are called <tt>profiles.xml</tt>,
87	<tt>tagging.xml</tt> and <tt>translations.xml</tt>. The names of the
88	configuration files can be specified on the command line but by default are also
89	looked for in the directory that contains the routing database.
90
91
92	<h2><a name="H_1_3"></a>Example Web Page</h2>
93
94	The directory <tt>web</tt> contains a set of files that can be used to create a
95	working set of web pages with interfaces to the routing algorithm.
96
97	<p>
98
99	The files in the <tt>web</tt> directory will require copying to a location that
100	is accessible by a web server. After copying the files some of them need to be
101	edited; search through the files for lines that contain the words "EDIT THIS"
102	and make appropriate edits. The files that need editing are <tt>paths.pl</tt>
103	(to set the directory paths) and <tt>router.js</tt> and <tt>visualiser.js</tt>
104	to limit the range of the visible map (latitude, longitude and zoom).
105
106
107	<h3><a name="H_1_3_1"></a>Configuration of web files</h3>
108
109	The assumption in this description is that the whole of the directory called
110	<tt>web</tt> is copied into a directory that is accessible by an Apache web
111	server.
112
113	<p>
114
115	<em>This is not a secure configuration but an easy one to configure.</em>
116	<br>
117	<em>Only the directory <tt>www</tt> should be accessible by the web server.</em>
118	<br>
119	<em>Do not use this configuration unmodified in a public web server.</em>
120
121	<p>
122
123	The directory structure is as follows:
124
125	<pre>
126	web/
127	\|
128	+ /bin/ <- The Routino executable files (when compiled).
129	\|
130	+ /data/ <- The Routino database and default configuration
131	\| files.
132	\|
133	+ /results/ <- An empty directory to store the results.
134	\|
135	+ /www/ <- The files that must be available to the web
136	\| server are below this level.
137	\|
138	+ /openlayers/ <- A directory to hold the OpenLayers scripts.
139	\|
140	+ /routino/ <- The main HTML, Javascript, CSS and CGI files.
141	\|
142	+ /documentation/ <- The HTML version of the Routino documentation.
143	</pre>
144
145	The directory <tt>bin</tt> will be filled by running the compilation process.
146	For a secure installation the <tt>bin</tt> directory should be outside of the
147	web server, the file <tt>www/routino/paths.pl</tt> contains the path to
148	the <tt>bin</tt> directory.
149
150	<p>
151
152	The directory <tt>data</tt> must contain the Routino database and is also the
153	default location for the configuration files. The routing database is created
154	by downloading the OSM files for the region of interest and running the
155	planetsplitter program. There is a script in the directory that will download
156	the OSM files and create the required database. The script should be edited to
157	set the names of the files to be downloaded. For a secure installation
158	the <tt>data</tt> directory should be outside of the web server, the
159	file <tt>www/routino/paths.pl</tt> contains the path to the <tt>data</tt>
160	directory.
161
162	<p>
163
164	The directory <tt>results</tt> is a temporary directory that it used to hold the
165	GPX and text files generated by the Routino router. The directory must be
166	writable by the web server process since it is the CGI scripts that are run by
167	the web server that writes the results here. For a secure installation
168	the <tt>results</tt> directory should be outside of the web server, the file
169	<tt>www/routino/paths.pl</tt> contains the path to the <tt>results</tt> directory.
170
171	<p>
172
173	The directory <tt>www</tt> and its sub-directories are the only ones that need
174	to be within the web server accessible directory.
175
176	<p>
177
178	The directory <tt>www/openlayers</tt> must be filled with the openlayers
179	Javascript library that can be downloaded from http://www.openlayers.org/.
180	(This version of Routino has been tested with OpenLayers library version 2.9.1).
181	The files must be installed so that the file <tt>www/openlayers/OpenLayers.js</tt>
182	and the directories <tt>www/openlayers/img/</tt>, <tt>www/openlayers/theme/</tt>
183	all exist. There is a script in the directory that will automatically download
184	the files, create an optimised "OpenLayers.js" and copy the files to the required
185	locations.
186
187	<p>
188
189	The directory <tt>www/routino</tt> contains the main HTML, Javascript and CSS
190	files as well as the CGI scripts that perform the server-side routing functions.
191	The description below lists all of the files that contain editable information.
192
193	<dl>
194	<dt>paths.pl
195	<dd>This contains the names of the directories that contain the executable
196	files, router database and temporary results.
197	<dt>router.pl
198	<dd>This file contains the filename prefix for the routing database files
199	(only needed if planetsplitter is run with the --prefix option).
200	<dt>router.js
201	<dd>The parameters in this file control the boundary of the visible map
202	(defaults to UK), the minimum and maximum zoom levels (defaults to between
203	4 and 15 inclusive) and the source of map tiles (defaults to the main
204	OpenStreetMap tile server).
205	<dt>visualiser.js
206	<dd>The same parameters as in router.js are in this file.
207	</dl>
208
209	<p>
210
211	The directory <tt>www/routino/documentation</tt> contains the HTML version of
212	the Routino documentation.
213
214
215	<h3><a name="H_1_3_2"></a>Configuration of web server</h3>
216
217	The file <tt>www/routino/.htaccess</tt> contains all of the Apache configuration
218	options that are required to get the example web pages running. The only
219	problem is that because of the way that the <tt>AllowOverride</tt> option works
220	one of the configuration options has been commented out. This must be enabled
221	in the main Apache server configuration file.
222
223
224	</div>
225
226	<!-- Content End -->
227
228	<!-- Footer Start -->
229
230	<div class="footer" align="center">
231	<hr>
232
233	<address>
234	© Andrew M. Bishop = <amb "at" gedanken.demon.co.uk>
235	</address>
236
237	</div>
238
239	<!-- Footer End -->
240
241	</BODY>
242
243	</HTML>