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 16
   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 forgot `--recursive`, 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 build
  46       wget --no-verbose --output-document=/tmp/monaco.osm.pbf http://download.geofabrik.de/europe/monaco-latest.osm.pbf
  47       ./utils/setup.php --osm-file /tmp/monaco.osm.pbf --osm2pgsql-cache 1000 --all 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 [locahost: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/lib for example you first need to copy them into the
  66 /build directory.
  67
  68 PHP errors are written to `/var/log/apache2/error.log`.
  69
  70 With `echo` and `var_dump()` you write into the output (HTML/XML/JSON) when
  71 you either add `&debug=1` to the URL (preferred) or set
  72 `@define('CONST_Debug', true);` in `settings/local.php`.
  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 `/features/db` and `/features/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/ features/api/reverse.feature
 106
 107 To run specific tests you can add tags just before the `Scenario line`, e.g.
 108
 109     @bug-34
 110     Scenario: address lookup for non-existing or invalid node, way, relation
 111
 112 and then
 113
 114     behave -DBUILDDIR=/home/vagrant/build/ --tags @bug-34
 115
 116
 117
 118
 119
 120
 121 ## FAQ
 122
 123 ##### Will it run on Windows?
 124
 125 Yes, Vagrant and Virtualbox can be installed on MS Windows just fine. You need a 64bit
 126 version of Windows.
 127
 128
 129 ##### Why Monaco, can I use another country?
 130
 131 Of course! The Monaco import takes less than 30 minutes and works with 2GB RAM.
 132
 133 ##### Will the results be the same as those from nominatim.openstreetmap.org?
 134
 135 No. Long running Nominatim installations will differ once new import features (or
 136 bug fixes) get added since those usually only get applied to new/changed data.
 137
 138 Also this document skips the optional Wikipedia data import which affects ranking
 139 of search results. See [Nominatim installation](http://nominatim.org/release-docs/latest/Installation) for details.
 140
 141 ##### Why Ubuntu? Can I test CentOS/Fedora/CoreOS/FreeBSD?
 142
 143 There is a Vagrant script for CentOS available, but the Nominatim directory
 144 isn't symlinked/mounted to the host which makes development trickier. We used
 145 it mainly for debugging installation with SELinux.
 146
 147 In general Nominatim will run in the other environments. The installation steps
 148 are slightly different, e.g. the name of the package manager, Apache2 package
 149 name, location of files. We chose Ubuntu because that is closest to the
 150 nominatim.openstreetmap.org production environment.
 151
 152 You can configure/download other Vagrant boxes from [https://app.vagrantup.com/boxes/search](https://app.vagrantup.com/boxes/search).
 153
 154 ##### How can I connect to an existing database?
 155
 156 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.
 157
 158     pgsql://postgres@your-server.com:5432/nominatim_it
 159
 160 No data import necessary or restarting necessary.
 161
 162 If the Postgres installation is behind a firewall, you can try
 163
 164     ssh -L 9999:localhost:5432 your-username@your-server.com
 165
 166 inside the virtual machine. It will map the port to `localhost:9999` and then
 167 you edit `settings/local.php` with
 168
 169     @define('CONST_Database_DSN', 'pgsql://postgres@localhost:9999/nominatim_it');
 170
 171 To access postgres directly remember to specify the hostname, e.g. `psql --host localhost --port 9999 nominatim_it`
 172
 173
 174 ##### My computer is slow and the import takes too long. Can I start the virtual machine "in the cloud"?
 175
 176 Yes. It's possible to start the virtual machine on [Amazon AWS (plugin)](https://github.com/mitchellh/vagrant-aws)
 177 or [DigitalOcean (plugin)](https://github.com/smdahlen/vagrant-digitalocean).
 178
 179
 180
 181