Routino SVN Repository Browser

Check out the latest version of Routino: svn co http://routino.org/svn/trunk routino

ViewVC logotype

Contents of /trunk/doc/INSTALL.txt

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1514 - (show annotations) (download)
Sat Feb 22 14:00:03 2014 UTC (11 years ago) by amb
File MIME type: text/plain
File size: 13016 byte(s)
Add the option for automatic uncompression of .xz compressed files (not enabled
by default in Makefile.conf).

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

Properties

Name Value
cvs:description Description of compilation and installation.