Check out the latest version of Routino: svn co http://routino.org/svn/trunk routino
Annotation of /trunk/doc/INSTALL.txt
Parent Directory
|
Revision Log
Revision 2123 -
(hide annotations)
(download)
Tue Aug 9 14:27:56 2022 UTC (2 years, 7 months ago) by amb
File MIME type: text/plain
File size: 15092 byte(s)
Tue Aug 9 14:27:56 2022 UTC (2 years, 7 months ago) by amb
File MIME type: text/plain
File size: 15092 byte(s)
Fix name of default Apache configuration file.
1 | amb | 429 | Routino : Installation |
2 | ====================== | ||
3 | amb | 152 | |
4 | amb | 381 | |
5 | amb | 1453 | Quick Start Guide |
6 | ----------------- | ||
7 | |||
8 | The instructions below are a complete list of the minimum required to | ||
9 | amb | 1699 | 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 | amb | 1453 | |
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 | amb | 1888 | 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 | amb | 1453 | |
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 | amb | 1529 | cd /var/www/routino/data |
48 | sh -x create.sh | ||
49 | |||
50 | amb | 2005 | 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 | amb | 1453 | |
54 | amb | 2004 | cd /var/www/routino/www/openlayers2 |
55 | amb | 1453 | sh -x install.sh |
56 | |||
57 | amb | 1492 | cd /var/www/routino/www/leaflet |
58 | sh -x install.sh | ||
59 | |||
60 | amb | 1947 | To run the Perl scripts that are used on the Routino web page you will |
61 | need to install some extra perl packages. | ||
62 | amb | 1453 | |
63 | amb | 1947 | apt-get install libcgi-pm-perl libwww-perl liburi-perl libjson-pp-perl |
64 | amb | 1453 | |
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 | amb | 2123 | vi /etc/apache2/sites-enabled/000-default.conf |
71 | amb | 1453 | 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 | amb | 1269 | 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 | amb | 1343 | (gcc, make). The compilation tools to use and the command line options |
94 | are defined in the file 'Makefile.conf'. | ||
95 | amb | 1269 | |
96 | There is some support for multi-threading that uses pthreads and | ||
97 | amb | 1512 | 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 | amb | 1514 | time by commenting out two lines in the file 'Makefile.conf'. |
101 | amb | 1269 | |
102 | amb | 1512 | 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 | amb | 1269 | |
108 | amb | 1512 | 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 | amb | 1514 | 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 | amb | 1583 | 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 | amb | 1269 | 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 | amb | 1583 | 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 | amb | 1269 | |
134 | amb | 152 | Compilation |
135 | amb | 381 | ----------- |
136 | amb | 152 | |
137 | amb | 1936 | 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 | amb | 1269 | |
141 | amb | 1936 | 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 | amb | 2058 | 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 | amb | 152 | This program has been written to run on Linux, no cross-platform |
159 | amb | 429 | compatibility has been specifically included but on the other hand |
160 | amb | 1269 | other platforms have not knowingly been excluded either. |
161 | amb | 152 | |
162 | amb | 429 | Any information on improving the compilation process on anything other |
163 | amb | 1269 | than x86 Linux is welcome. |
164 | amb | 152 | |
165 | |||
166 | amb | 429 | Installation |
167 | ------------ | ||
168 | amb | 152 | |
169 | amb | 429 | 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 | amb | 191 | |
175 | amb | 1274 | 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 | amb | 1345 | The 'filedumperx' executable is for debugging and not required. |
179 | amb | 191 | |
180 | amb | 1274 | 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 | amb | 1453 | directory that contains the routing database with these names. |
184 | amb | 381 | |
185 | amb | 191 | |
186 | amb | 429 | Example Web Page |
187 | ---------------- | ||
188 | |||
189 | amb | 515 | 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 | amb | 191 | |
192 | amb | 515 | 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 | amb | 1269 | editing are 'paths.pl' (to set the directory paths) and 'mapprops.js' (to |
197 | amb | 998 | set the map properties). |
198 | amb | 191 | |
199 | amb | 381 | |
200 | amb | 191 | Configuration of web files |
201 | amb | 381 | -------------------------- |
202 | amb | 191 | |
203 | amb | 429 | 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 | amb | 191 | |
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 | amb | 423 | + /bin/ <- The Routino executable files (when compiled). |
218 | amb | 191 | | |
219 | amb | 423 | + /data/ <- The Routino database and default configuration |
220 | | files. | ||
221 | amb | 191 | | |
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 | amb | 2005 | + /openlayers2/ <- A directory to hold the older OpenLayers v2 |
228 | | library (optional; newer openlayers or leaflet | ||
229 | | can be used instead). | ||
230 | amb | 191 | | |
231 | amb | 2005 | + /openlayers/ <- A directory to hold the newer OpenLayers |
232 | | library (optional; older openlayers v2 or | ||
233 | | leaflet can be used instead). | ||
234 | | | ||
235 | amb | 1492 | + /leaflet/ <- A directory to hold the Leaflet library. |
236 | amb | 2005 | | (optional; older openlayers v2 or newer |
237 | | openlayers can be used instead). | ||
238 | amb | 1492 | | |
239 | amb | 191 | + /routino/ <- The main HTML, Javascript, CSS and CGI files. |
240 | amb | 515 | | |
241 | + /documentation/ <- The HTML version of the Routino documentation. | ||
242 | amb | 191 | |
243 | amb | 429 | 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 | amb | 515 | web server, the file 'www/routino/paths.pl' contains the path to the |
246 | 'bin' directory. | ||
247 | amb | 191 | |
248 | amb | 423 | The directory 'data' must contain the Routino database and is also the |
249 | amb | 429 | default location for the configuration files. The routing database is |
250 | created by downloading the OSM files for the region of interest and | ||
251 | amb | 515 | 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 | amb | 191 | |
258 | amb | 515 | 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 | amb | 191 | |
266 | amb | 429 | The directory 'www' and its sub-directories are the only ones that need |
267 | to be within the web server accessible directory. | ||
268 | amb | 191 | |
269 | amb | 2005 | 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 | amb | 1492 | |
274 | amb | 2005 | The directory www/openlayers2 is for the older OpenLayers version 2 |
275 | Javascript library that can be downloaded from | ||
276 | amb | 2010 | http://www.openlayers.org/two/. (This version of Routino has been tested |
277 | amb | 2005 | 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 | amb | 191 | |
282 | amb | 2005 | 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 | amb | 2083 | with OpenLayers library version 6.4.3). There is a script in the |
286 | amb | 2005 | www/openlayers directory that will automatically download the files. |
287 | amb | 1492 | |
288 | amb | 2005 | The directory www/leaflet is for the Leaflet Javascript library that |
289 | can be downloaded from http://leafletjs.com/. (This version of Routino | ||
290 | amb | 2083 | has been tested with Leaflet library version 1.7.1). There is a script |
291 | amb | 2005 | in the www/leaflet directory that will automatically download the |
292 | files. | ||
293 | |||
294 | amb | 429 | The directory 'www/routino' contains the main HTML, Javascript and CSS |
295 | amb | 515 | files as well as the CGI scripts that perform the server-side routing |
296 | amb | 429 | functions. The description below lists all of the files that contain |
297 | editable information. | ||
298 | amb | 191 | |
299 | amb | 429 | paths.pl |
300 | This contains the names of the directories that contain the | ||
301 | amb | 998 | executable files, router database and temporary results; the |
302 | prefix for the routing database; and the names of the | ||
303 | executables. | ||
304 | amb | 191 | |
305 | amb | 1012 | mapprops.js |
306 | amb | 1492 | The parameters in this file control the Javascript map library |
307 | amb | 2004 | (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 | amb | 191 | |
314 | amb | 515 | The directory www/routino/documentation contains the HTML version of |
315 | the Routino documentation. | ||
316 | amb | 381 | |
317 | amb | 901 | |
318 | amb | 1583 | Configuration of Web Server |
319 | amb | 1529 | --------------------------- |
320 | amb | 191 | |
321 | amb | 1853 | 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 | amb | 191 | |
327 | amb | 1453 | 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 | amb | 1425 | |
331 | amb | 1453 | <Directory /var/www/routino> |
332 | amb | 1853 | AllowOverride Options=MultiViews,ExecCGI FileInfo Limit |
333 | amb | 1425 | </Directory> |
334 | amb | 191 | |
335 | amb | 1453 | 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 | amb | 1425 | |
338 | amb | 1453 | |
339 | amb | 152 | -------- |
340 | |||
341 | amb | 2058 | Copyright 2008-2020 Andrew M. Bishop. |
Properties
Name | Value |
---|---|
cvs:description | Description of compilation and installation. |