]> git.openstreetmap.org Git - nominatim.git/blob - VAGRANT.md
Vagrant: use 2GB by default, dont overwrite local.php which would be unexpected
[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
34
35 2. Log into the virtual machine
36
37         vagrant ssh
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   cd Nominatim
49     wget --no-verbose --output-document=data/monaco.osm.pbf http://download.geofabrik.de/europe/monaco-latest.osm.pbf
50     ./utils/setup.php --osm-file data/monaco.osm.pbf --osm2pgsql-cache 1000 --all 2>&1 | tee monaco.$$.log
51     ./utils/specialphrases.php --countries > data/specialphrases_countries.sql
52     psql -d nominatim -f data/specialphrases_countries.sql
53     ```
54
55   To repeat an import you'd need to delete the database first
56
57         dropdb --username postgres -if-exists nominatim
58
59
60
61 ## Development
62
63 Vagrant maps the virtual machine's port 8089 to your host machine. Thus you can
64 see Nominatim in action on [locahost:8089](http://localhost:8089/nominatim/).
65
66 You edit code on your host machine in any editor you like. There is no need to
67 restart any software: just refresh your browser window.
68
69 PHP errors are written to `/var/log/apache2/error.log`.
70
71 With `echo` and `var_dump()` you write into the output (HTML/XML/JSON) when
72 you either add `&debug=1` to the URL (preferred) or set
73 `@define('CONST_Debug', true);` in `settings/local.php`.
74
75
76
77
78 ## Running functional tests
79
80 Tests in `/features/db` and `/features/osm2pgsql` have to pass 100%. Other
81 tests might require full planet-wide data. Sadly even if you have your own
82 planet-wide data there will be enough differences to the openstreetmap.org
83 installation to cause false positives in the other tests (see FAQ). 
84
85 To run the full test suite
86
87     cd ~/Nominatim/tests
88     NOMINATIM_SERVER=http://localhost:8089/nominatim lettuce features
89
90 To run a single file
91
92     NOMINATIM_SERVER=http://localhost:8089/nominatim lettuce features/api/reverse.feature
93     
94 To run specific tests you can add tags just before the `Scenario line`, e.g.
95
96     @bug-34
97     Scenario: address lookup for non-existing or invalid node, way, relation
98
99 and then
100
101     NOMINATIM_SERVER=http://localhost:8089/nominatim lettuce -t bug-34
102
103
104 ## Running unit tests
105
106     cd ~/Nominatim/tests-php
107     phpunit ./
108
109
110
111
112
113
114 ## FAQ
115
116 ##### Will it run on Windows?
117
118 Yes, Vagrant and Virtualbox can be installed on MS Windows just fine. You need a 64bit
119 version of Windows.
120
121
122 ##### Why Monaco, can I use another country?
123
124 Of course! The Monaco import takes less than 30 minutes and works with 2GB RAM.
125
126 ##### Will the results be the same as those from nominatim.openstreetmap.org?
127
128 No. Long running Nominatim installations will differ once new import features (or
129 bug fixes) get added since those usually only get applied to new/changed data.
130
131 Also this document skips the optional Wikipedia data import which affects ranking
132 of search results. See [Nominatim instllation](http://wiki.openstreetmap.org/wiki/Nominatim/Installation) for details.
133
134 ##### Why Ubuntu, can I test CentOS/CoreOS/FreeBSD?
135
136 In general Nominatim will run in all these environment. The installation steps
137 are slightly different, e.g. the name of the package manager, Apache2 package
138 name, location of files. We chose Ubuntu because that is closest to the
139 nominatim.openstreetmap.org production environment.
140
141 You can configure/download other Vagrant boxes from [vagrantbox.es](http://www.vagrantbox.es/).
142
143
144 ##### How can I connect to an existing database?
145
146 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.
147
148     pgsql://postgres@your-server.com:5432/nominatim_it
149     
150 No data import necessary, no restarting necessary.
151
152 If the Postgres installation is behind a firewall, you can try
153
154     ssh -L 9999:localhost:5432 your-username@your-server.com
155
156 inside the virtual machine. It will map the port to `localhost:9999` and then
157 you edit `settings/local.php` with
158
159     pgsql://postgres@localhost:9999/nominatim_it
160
161
162 ##### My computer is slow and the import takes too long. Can I start the virtual machine "in the cloud"?
163
164 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).
165
166
167
168