Merge remote-tracking branch 'upstream/master'

[nominatim.git] / VAGRANT.md

diff --git a/VAGRANT.md b/VAGRANT.md
index 3a8e479bde7283329dfc4c02064d1a4bead35ed8..b10a5ac779cc9e9fe756f7e375e838ad0a37a827 100644 (file)
--- a/VAGRANT.md
+++ b/VAGRANT.md
@@ -1,11 +1,11 @@
 # Install Nominatim in a virtual machine for development and testing
 
 # Install Nominatim in a virtual machine for development and testing
 

-This document describes how you can install Nominatim inside a Ubuntu 14
+This document describes how you can install Nominatim inside a Ubuntu 16

 virtual machine on your desktop/laptop (host machine). The goal is to give
 you a development environment to easily edit code and run the test suite
 without affecting the rest of your system. 
 
 virtual machine on your desktop/laptop (host machine). The goal is to give
 you a development environment to easily edit code and run the test suite
 without affecting the rest of your system. 
 

-The installation can run largely unsupervised. You should expect 1-2h from
+The installation can run largely unsupervised. You should expect 1h from

 start to finish depending on how fast your computer and download speed
 is.
 
 start to finish depending on how fast your computer and download speed
 is.
 


@@ -17,9 +17,9 @@ is.
 
 3. Nominatim 
 
 
 3. Nominatim 
 

-        git clone --recursive https://github.com/twain47/Nominatim.git
+        git clone --recursive https://github.com/openstreetmap/Nominatim.git

 
 

-    If you haven't used `--recursive`, then you can load the submodules using
+    If you forgot `--recursive`, it you can later load the submodules using

     
         git submodule init
         git submodule update
     
         git submodule init
         git submodule update


@@ -30,31 +30,26 @@ is.
 
 1. Start the virtual machine
 
 
 1. Start the virtual machine
 

-        vagrant up
+        vagrant up ubuntu

 
 2. Log into the virtual machine
 
 
 2. Log into the virtual machine
 

-        vagrant ssh
+        vagrant ssh ubuntu

 
 3. Import a small country (Monaco)
 
 3. Import a small country (Monaco)

-
-    You need to give the virtual machine more memory (2GB) for an import,
-    see `Vagrantfile`. Otherwise 1GB is enough.

     
     See the FAQ how to skip this step and point Nominatim to an existing database.
 
     
     See the FAQ how to skip this step and point Nominatim to an existing database.
 

-  ```
-  # inside the virtual machine:
-  cd Nominatim
-    wget --no-verbose --output-document=data/monaco.osm.pbf http://download.geofabrik.de/europe/monaco-latest.osm.pbf
-    ./utils/setup.php --osm-file data/monaco.osm.pbf --osm2pgsql-cache 1000 --all 2>&1 | tee monaco.$$.log
-    ./utils/specialphrases.php --countries > data/specialphrases_countries.sql
-    psql -d nominatim -f data/specialphrases_countries.sql
-    ```
+      ```
+      # inside the virtual machine:
+      cd build
+      wget --no-verbose --output-document=/tmp/monaco.osm.pbf http://download.geofabrik.de/europe/monaco-latest.osm.pbf
+      ./utils/setup.php --osm-file /tmp/monaco.osm.pbf --osm2pgsql-cache 1000 --all 2>&1 | tee monaco.$$.log
+      ```

 
 

-  To repeat an import you'd need to delete the database first
+    To repeat an import you'd need to delete the database first

 
 

-        dropdb --username postgres -if-exists nominatim
+        dropdb --if-exists nominatim

 
 
 
 
 
 


@@ -66,45 +61,62 @@ see Nominatim in action on [locahost:8089](http://localhost:8089/nominatim/).
 You edit code on your host machine in any editor you like. There is no need to
 restart any software: just refresh your browser window.
 
 You edit code on your host machine in any editor you like. There is no need to
 restart any software: just refresh your browser window.
 

+Note that the webserver uses files from the /build directory. If you change
+files in Nominatim/website or Nominatim/utils for example you first need to
+copy them into the /build directory by running the `cmake` step from the
+installation.
+

 PHP errors are written to `/var/log/apache2/error.log`.
 
 With `echo` and `var_dump()` you write into the output (HTML/XML/JSON) when
 you either add `&debug=1` to the URL (preferred) or set
 `@define('CONST_Debug', true);` in `settings/local.php`.
 
 PHP errors are written to `/var/log/apache2/error.log`.
 
 With `echo` and `var_dump()` you write into the output (HTML/XML/JSON) when
 you either add `&debug=1` to the URL (preferred) or set
 `@define('CONST_Debug', true);` in `settings/local.php`.
 

+In the Python BDD test you can use `logger.info()` for temporary debug
+statements.
+
+
+
+## Running unit tests
+
+    cd ~/Nominatim/tests/php
+    phpunit ./
+
+
+## Running PHP code style tests

 
 

+    cd ~/Nominatim
+    phpcs --colors .

 
 
 ## Running functional tests
 
 
 
 ## Running functional tests
 

-Tests in `/features/db` and `/features/osm2pgsql` have to pass 100%. Other
+Tests in `test/bdd/db` and `test/bdd/osm2pgsql` have to pass 100%. Other

 tests might require full planet-wide data. Sadly even if you have your own
 planet-wide data there will be enough differences to the openstreetmap.org
 installation to cause false positives in the other tests (see FAQ). 
 
 To run the full test suite
 
 tests might require full planet-wide data. Sadly even if you have your own
 planet-wide data there will be enough differences to the openstreetmap.org
 installation to cause false positives in the other tests (see FAQ). 
 
 To run the full test suite
 

-    cd ~/Nominatim/tests
-    NOMINATIM_SERVER=http://localhost:8089/nominatim lettuce features
+    cd ~/Nominatim/test/bdd
+    behave -DBUILDDIR=/home/vagrant/build/ db osm2pgsql

 
 To run a single file
 
 
 To run a single file
 

-    NOMINATIM_SERVER=http://localhost:8089/nominatim lettuce features/api/reverse.feature
+    behave -DBUILDDIR=/home/vagrant/build/ api/lookup/simple.feature
+
+Or a single test by line number
+
+    behave -DBUILDDIR=/home/vagrant/build/ api/lookup/simple.feature:34

     
     

-To run specific tests you can add tags just before the `Scenario line`, e.g.
+To run specific groups of tests you can add tags just before the `Scenario line`, e.g.

 
     @bug-34
     Scenario: address lookup for non-existing or invalid node, way, relation
 
 and then
 
 
     @bug-34
     Scenario: address lookup for non-existing or invalid node, way, relation
 
 and then
 

-    NOMINATIM_SERVER=http://localhost:8089/nominatim lettuce -t bug-34
-
-
-## Running unit tests
-
-    cd ~/Nominatim/tests-php
-    phpunit ./
+    behave -DBUILDDIR=/home/vagrant/build/ --tags @bug-34

 
 
 
 
 
 


@@ -129,25 +141,28 @@ No. Long running Nominatim installations will differ once new import features (o
 bug fixes) get added since those usually only get applied to new/changed data.
 
 Also this document skips the optional Wikipedia data import which affects ranking
 bug fixes) get added since those usually only get applied to new/changed data.
 
 Also this document skips the optional Wikipedia data import which affects ranking

-of search results. See [Nominatim installation](http://wiki.openstreetmap.org/wiki/Nominatim/Installation) for details.
+of search results. See [Nominatim installation](https://nominatim.org/release-docs/latest/admin/Installation) for details.

 
 

-##### Why Ubuntu, can I test CentOS/CoreOS/FreeBSD?
+##### Why Ubuntu? Can I test CentOS/Fedora/CoreOS/FreeBSD?

 
 

-In general Nominatim will run in all these environment. The installation steps
+There is a Vagrant script for CentOS available, but the Nominatim directory
+isn't symlinked/mounted to the host which makes development trickier. We used
+it mainly for debugging installation with SELinux.
+
+In general Nominatim will run in the other environments. The installation steps

 are slightly different, e.g. the name of the package manager, Apache2 package
 name, location of files. We chose Ubuntu because that is closest to the
 nominatim.openstreetmap.org production environment.
 
 are slightly different, e.g. the name of the package manager, Apache2 package
 name, location of files. We chose Ubuntu because that is closest to the
 nominatim.openstreetmap.org production environment.
 

-You can configure/download other Vagrant boxes from [vagrantbox.es](http://www.vagrantbox.es/).
-
+You can configure/download other Vagrant boxes from [https://app.vagrantup.com/boxes/search](https://app.vagrantup.com/boxes/search).

 
 ##### How can I connect to an existing database?
 
 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.
 
 
 ##### How can I connect to an existing database?
 
 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.
 

-    pgsql://postgres@your-server.com:5432/nominatim_it
+    pgsql:host=your-server.com;port=5432;user=postgres;dbname=nominatim_it

     
     

-No data import necessary, no restarting necessary.
+No data import or restarting necessary.

 
 If the Postgres installation is behind a firewall, you can try
 
 
 If the Postgres installation is behind a firewall, you can try
 


@@ -156,14 +171,15 @@ If the Postgres installation is behind a firewall, you can try
 inside the virtual machine. It will map the port to `localhost:9999` and then
 you edit `settings/local.php` with
 
 inside the virtual machine. It will map the port to `localhost:9999` and then
 you edit `settings/local.php` with
 

-    pgsql://postgres@localhost:9999/nominatim_it
+    @define('CONST_Database_DSN', 'pgsql:host=localhost;port=9999;user=postgres;dbname=nominatim_it');

 
 To access postgres directly remember to specify the hostname, e.g. `psql --host localhost --port 9999 nominatim_it`
 
 
 ##### My computer is slow and the import takes too long. Can I start the virtual machine "in the cloud"?
 
 
 To access postgres directly remember to specify the hostname, e.g. `psql --host localhost --port 9999 nominatim_it`
 
 
 ##### My computer is slow and the import takes too long. Can I start the virtual machine "in the cloud"?
 

-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).
+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).