Routino SVN Repository Browser

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

ViewVC logotype

Annotation of /trunk/doc/INSTALL.txt

Parent Directory Parent Directory | Revision Log 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)
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.