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 24
   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 https://github.com/openstreetmap/Nominatim.git
  21
  22 ## Installation
  23
  24 1. Start the virtual machine
  25
  26         vagrant up ubuntu24-nginx
  27
  28 2. Log into the virtual machine
  29
  30         vagrant ssh ubuntu24-nginx
  31
  32 3. Import a small country (Monaco)
  33
  34     See the FAQ how to skip this step and point Nominatim to an existing database.
  35
  36       ```
  37       # inside the virtual machine:
  38       cd nominatim-project
  39       wget --no-verbose --output-document=monaco.osm.pbf http://download.geofabrik.de/europe/monaco-latest.osm.pbf
  40       nominatim import --osm-file monaco.osm.pbf 2>&1 | tee monaco.$$.log
  41       ```
  42
  43     To repeat an import you'd need to delete the database first
  44
  45         dropdb --if-exists nominatim
  46
  47
  48
  49 ## Development
  50
  51 Vagrant maps the virtual machine's port 8089 to your host machine. Thus you can
  52 see Nominatim in action on [localhost:8089](http://localhost:8089/nominatim/).
  53
  54 You edit code on your host machine in any editor you like. There is no need to
  55 restart any software: just refresh your browser window.
  56
  57 Use the functions of the `log()` object to create temporary debug output.
  58 Add `&debug=1` to the URL to see the output.
  59
  60 In the Python BDD test you can use `logger.info()` for temporary debug
  61 statements.
  62
  63 For more information on running tests, see
  64 https://nominatim.org/release-docs/develop/develop/Testing/
  65
  66
  67 ## FAQ
  68
  69 ##### Will it run on Windows?
  70
  71 Yes, Vagrant and Virtualbox can be installed on MS Windows just fine. You need
  72 a 64bit version of Windows.
  73
  74 ##### Will it run on Apple Silicon?
  75
  76 You might need to replace Virtualbox with [Parallels](https://www.parallels.com/products/desktop/).
  77 There is no free/open source version of Parallels.
  78
  79 ##### Why Monaco, can I use another country?
  80
  81 Of course! The Monaco import takes less than 10 minutes and works with 2GB RAM.
  82
  83 ##### Will the results be the same as those from nominatim.openstreetmap.org?
  84
  85 No. Long-running Nominatim installations will differ once new import features (or
  86 bug fixes) get added since those usually only get applied to new/changed data.
  87
  88 Also this document skips the optional Wikipedia data import which affects ranking
  89 of search results. See [Nominatim installation](https://nominatim.org/release-docs/latest/admin/Installation)
  90 for details.
  91
  92 ##### Why Ubuntu? Can I test CentOS/Fedora/CoreOS/FreeBSD?
  93
  94 There used to be a Vagrant script for CentOS available, but the Nominatim directory
  95 isn't symlinked/mounted to the host which makes development trickier. We used
  96 it mainly for debugging installation with SELinux.
  97
  98 In general Nominatim will run in the other environments. The installation steps
  99 are slightly different, e.g. the name of the package manager, Apache2 package
 100 name, location of files. We chose Ubuntu because that is closest to the
 101 nominatim.openstreetmap.org production environment.
 102
 103 You can configure/download other Vagrant boxes from
 104 [https://app.vagrantup.com/boxes/search](https://app.vagrantup.com/boxes/search).
 105
 106 ##### How can I connect to an existing database?
 107
 108 Let's say you have a Postgres database named `nominatim_it` on server `your-server.com`
 109 and port `5432`. The Postgres username is `postgres`. You can edit the `.env` in your
 110 project directory and point Nominatim to it.
 111
 112     NOMINATIM_DATABASE_DSN="pgsql:host=your-server.com;port=5432;user=postgres;dbname=nominatim_it
 113
 114 No data import or restarting necessary.
 115
 116 If the Postgres installation is behind a firewall, you can try
 117
 118     ssh -L 9999:localhost:5432 your-username@your-server.com
 119
 120 inside the virtual machine. It will map the port to `localhost:9999` and then
 121 you edit `.env` file with
 122
 123     NOMINATIM_DATABASE_DSN="pgsql:host=localhost;port=9999;user=postgres;dbname=nominatim_it"
 124
 125 To access postgres directly remember to specify the hostname,
 126 e.g. `psql --host localhost --port 9999 nominatim_it`
 127
 128
 129 ##### My computer is slow and the import takes too long. Can I start the virtual machine "in the cloud"?
 130
 131 Yes. It's possible to start the virtual machine on [Amazon AWS (plugin)](https://github.com/mitchellh/vagrant-aws)
 132 or [DigitalOcean (plugin)](https://github.com/smdahlen/vagrant-digitalocean).