]> git.openstreetmap.org Git - nominatim.git/blob - VAGRANT.md
geocodejson: admin level output should only print boundaries
[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 22
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 1h 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/openstreetmap/Nominatim.git
21
22     If you forgot `--recursive`, it you can later 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     See the FAQ how to skip this step and point Nominatim to an existing database.
42
43       ```
44       # inside the virtual machine:
45       cd nominatim-project
46       wget --no-verbose --output-document=monaco.osm.pbf http://download.geofabrik.de/europe/monaco-latest.osm.pbf
47       nominatim import --osm-file monaco.osm.pbf 2>&1 | tee monaco.$$.log
48       ```
49
50     To repeat an import you'd need to delete the database first
51
52         dropdb --if-exists nominatim
53
54
55
56 ## Development
57
58 Vagrant maps the virtual machine's port 8089 to your host machine. Thus you can
59 see Nominatim in action on [localhost:8089](http://localhost:8089/nominatim/).
60
61 You edit code on your host machine in any editor you like. There is no need to
62 restart any software: just refresh your browser window.
63
64 Note that the webserver uses files from the /build directory. If you change
65 files in Nominatim/website or Nominatim/utils for example you first need to
66 copy them into the /build directory by running the `cmake` step from the
67 installation.
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.
73
74 In the Python BDD test you can use `logger.info()` for temporary debug
75 statements.
76
77
78
79 ## Running unit tests
80
81     cd ~/Nominatim/tests/php
82     phpunit ./
83
84
85 ## Running PHP code style tests
86
87     cd ~/Nominatim
88     phpcs --colors .
89
90
91 ## Running functional tests
92
93 Tests in `test/bdd/db` and `test/bdd/osm2pgsql` have to pass 100%. Other
94 tests might require full planet-wide data. Sadly even if you have your own
95 planet-wide data there will be enough differences to the openstreetmap.org
96 installation to cause false positives in the other tests (see FAQ). 
97
98 To run the full test suite
99
100     cd ~/Nominatim/test/bdd
101     behave -DBUILDDIR=/home/vagrant/build/ db osm2pgsql
102
103 To run a single file
104
105     behave -DBUILDDIR=/home/vagrant/build/ api/lookup/simple.feature
106
107 Or a single test by line number
108
109     behave -DBUILDDIR=/home/vagrant/build/ api/lookup/simple.feature:34
110     
111 To run specific groups of tests you can add tags just before the `Scenario line`, e.g.
112
113     @bug-34
114     Scenario: address lookup for non-existing or invalid node, way, relation
115
116 and then
117
118     behave -DBUILDDIR=/home/vagrant/build/ --tags @bug-34
119
120
121
122
123
124
125 ## FAQ
126
127 ##### Will it run on Windows?
128
129 Yes, Vagrant and Virtualbox can be installed on MS Windows just fine. You need a 64bit
130 version of Windows.
131
132 ##### Will it run on Apple Silicon?
133
134 You might need to replace Virtualbox with [Parallels](https://www.parallels.com/products/desktop/).
135 There is no free/open source version of Parallels.
136
137 ##### Why Monaco, can I use another country?
138
139 Of course! The Monaco import takes less than 30 minutes and works with 2GB RAM.
140
141 ##### Will the results be the same as those from nominatim.openstreetmap.org?
142
143 No. Long running Nominatim installations will differ once new import features (or
144 bug fixes) get added since those usually only get applied to new/changed data.
145
146 Also this document skips the optional Wikipedia data import which affects ranking
147 of search results. See [Nominatim installation](https://nominatim.org/release-docs/latest/admin/Installation)
148 for details.
149
150 ##### Why Ubuntu? Can I test CentOS/Fedora/CoreOS/FreeBSD?
151
152 There used to be a Vagrant script for CentOS available, but the Nominatim directory
153 isn't symlinked/mounted to the host which makes development trickier. We used
154 it mainly for debugging installation with SELinux.
155
156 In general Nominatim will run in the other environments. The installation steps
157 are slightly different, e.g. the name of the package manager, Apache2 package
158 name, location of files. We chose Ubuntu because that is closest to the
159 nominatim.openstreetmap.org production environment.
160
161 You can configure/download other Vagrant boxes from
162 [https://app.vagrantup.com/boxes/search](https://app.vagrantup.com/boxes/search).
163
164 ##### How can I connect to an existing database?
165
166 Let's say you have a Postgres database named `nominatim_it` on server `your-server.com`
167 and port `5432`. The Postgres username is `postgres`. You can edit the `.env` in your
168 project directory and point Nominatim to it.
169
170     NOMINATIM_DATABASE_DSN="pgsql:host=your-server.com;port=5432;user=postgres;dbname=nominatim_it
171
172 No data import or restarting necessary.
173
174 If the Postgres installation is behind a firewall, you can try
175
176     ssh -L 9999:localhost:5432 your-username@your-server.com
177
178 inside the virtual machine. It will map the port to `localhost:9999` and then
179 you edit `.env` file with
180
181     NOMINATIM_DATABASE_DSN="pgsql:host=localhost;port=9999;user=postgres;dbname=nominatim_it"
182
183 To access postgres directly remember to specify the hostname,
184 e.g. `psql --host localhost --port 9999 nominatim_it`
185
186
187 ##### My computer is slow and the import takes too long. Can I start the virtual machine "in the cloud"?
188
189 Yes. It's possible to start the virtual machine on [Amazon AWS (plugin)](https://github.com/mitchellh/vagrant-aws)
190 or [DigitalOcean (plugin)](https://github.com/smdahlen/vagrant-digitalocean).
191
192
193
194