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 To access postgres directly remember to specify the hostname, e.g. `psql --host localhost --port 9999 nominatim_it`
 162
 163
 164 ##### My computer is slow and the import takes too long. Can I start the virtual machine "in the cloud"?
 165
 166 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).
 167
 168
 169
 170