]> git.openstreetmap.org Git - nominatim.git/blob - VAGRANT.md
Merge remote-tracking branch 'upstream/master' into cmake-port
[nominatim.git] / VAGRANT.md
1 # Install Nominatim in a virtual machine for development and testing
2
3 This document describes how you can install Nominatim inside a Ubuntu 14
4 virtual machine on your desktop/laptop (host machine). The goal is to give
5 you a development environment to easily edit code and run the test suite
6 without affecting the rest of your system. 
7
8 The installation can run largely unsupervised. You should expect 1-2h from
9 start to finish depending on how fast your computer and download speed
10 is.
11
12 ## Prerequisites
13
14 1. [Virtualbox](https://www.virtualbox.org/wiki/Downloads)
15
16 2. [Vagrant](https://www.vagrantup.com/downloads.html)
17
18 3. Nominatim 
19
20         git clone --recursive https://github.com/twain47/Nominatim.git
21
22     If you haven't used `--recursive`, then you can load the submodules using
23     
24         git submodule init
25         git submodule update
26
27
28
29 ## Installation
30
31 1. Start the virtual machine
32
33         vagrant up ubuntu
34
35 2. Log into the virtual machine
36
37         vagrant ssh ubuntu
38
39 3. Import a small country (Monaco)
40
41     You need to give the virtual machine more memory (2GB) for an import,
42     see `Vagrantfile`. Otherwise 1GB is enough.
43     
44     See the FAQ how to skip this step and point Nominatim to an existing database.
45
46   ```
47   # inside the virtual machine:
48   mkdir data
49   cd build
50     wget --no-verbose --output-document=../data/monaco.osm.pbf http://download.geofabrik.de/europe/monaco-latest.osm.pbf
51     ./utils/setup.php --osm-file ../data/monaco.osm.pbf --osm2pgsql-cache 1000 --all 2>&1 | tee monaco.$$.log
52     ./utils/specialphrases.php --countries > ../data/specialphrases_countries.sql
53     psql -d nominatim -f ../data/specialphrases_countries.sql
54     ```
55
56   To repeat an import you'd need to delete the database first
57
58         dropdb -if-exists nominatim
59
60
61
62 ## Development
63
64 Vagrant maps the virtual machine's port 8089 to your host machine. Thus you can
65 see Nominatim in action on [locahost:8089](http://localhost:8089/nominatim/).
66
67 You edit code on your host machine in any editor you like. There is no need to
68 restart any software: just refresh your browser window.
69
70 PHP errors are written to `/var/log/apache2/error.log`.
71
72 With `echo` and `var_dump()` you write into the output (HTML/XML/JSON) when
73 you either add `&debug=1` to the URL (preferred) or set
74 `@define('CONST_Debug', true);` in `settings/local.php`.
75
76
77
78
79 ## Running functional tests
80
81 Tests in `/features/db` and `/features/osm2pgsql` have to pass 100%. Other
82 tests might require full planet-wide data. Sadly even if you have your own
83 planet-wide data there will be enough differences to the openstreetmap.org
84 installation to cause false positives in the other tests (see FAQ). 
85
86 To run the full test suite
87
88     cd ~/Nominatim/tests
89     NOMINATIM_SERVER=http://localhost:8089/nominatim lettuce features
90
91 To run a single file
92
93     NOMINATIM_SERVER=http://localhost:8089/nominatim lettuce features/api/reverse.feature
94     
95 To run specific tests you can add tags just before the `Scenario line`, e.g.
96
97     @bug-34
98     Scenario: address lookup for non-existing or invalid node, way, relation
99
100 and then
101
102     NOMINATIM_SERVER=http://localhost:8089/nominatim lettuce -t bug-34
103
104
105 ## Running unit tests
106
107     cd ~/Nominatim/tests-php
108     phpunit ./
109
110
111
112
113
114
115 ## FAQ
116
117 ##### Will it run on Windows?
118
119 Yes, Vagrant and Virtualbox can be installed on MS Windows just fine. You need a 64bit
120 version of Windows.
121
122
123 ##### Why Monaco, can I use another country?
124
125 Of course! The Monaco import takes less than 30 minutes and works with 2GB RAM.
126
127 ##### Will the results be the same as those from nominatim.openstreetmap.org?
128
129 No. Long running Nominatim installations will differ once new import features (or
130 bug fixes) get added since those usually only get applied to new/changed data.
131
132 Also this document skips the optional Wikipedia data import which affects ranking
133 of search results. See [Nominatim installation](http://wiki.openstreetmap.org/wiki/Nominatim/Installation) for details.
134
135 ##### Why Ubuntu and CentOS, can I test CentOS/CoreOS/FreeBSD?
136
137 There is a Vagrant script for CentOS available. Simply start your box
138 with `vagrant up centos` and then log in with `vagrant ssh centos`.
139 In general Nominatim will also run in the other environments. The installation steps
140 are slightly different, e.g. the name of the package manager, Apache2 package
141 name, location of files. We chose Ubuntu because that is closest to the
142 nominatim.openstreetmap.org production environment.
143
144 You can configure/download other Vagrant boxes from [vagrantbox.es](http://www.vagrantbox.es/).
145
146
147 ##### How can I connect to an existing database?
148
149 Let's say you have a Postgres database named `nominatim_it` on server `your-server.com` and port `5432`. The Postgres username is `postgres`. You can edit `settings/local.php` and point Nominatim to it.
150
151     pgsql://postgres@your-server.com:5432/nominatim_it
152     
153 No data import necessary, no restarting necessary.
154
155 If the Postgres installation is behind a firewall, you can try
156
157     ssh -L 9999:localhost:5432 your-username@your-server.com
158
159 inside the virtual machine. It will map the port to `localhost:9999` and then
160 you edit `settings/local.php` with
161
162     pgsql://postgres@localhost:9999/nominatim_it
163
164 To access postgres directly remember to specify the hostname, e.g. `psql --host localhost --port 9999 nominatim_it`
165
166
167 ##### My computer is slow and the import takes too long. Can I start the virtual machine "in the cloud"?
168
169 Yes. It's possible to start the virtual machine on [Amazon AWS (plugin)](https://github.com/mitchellh/vagrant-aws) or [DigitalOcean (plugin)](https://github.com/smdahlen/vagrant-digitalocean).
170
171
172
173