Check out the latest version of Routino: svn co http://routino.org/svn/trunk routino
Contents of /trunk/doc/INSTALL.txt
Parent Directory
|
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)
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. |