Skip to content

Setting up Nominatim for Development🔗

This chapter gives an overview how to set up Nominatim for development and how to run tests.

Important

This guide assumes you develop under the latest version of Debian/Ubuntu. You can of course also use your favourite distribution. You just might have to adapt the commands below slightly, in particular the commands for installing additional software.

Installing Nominatim🔗

The first step is to install Nominatim itself. Please follow the installation instructions in the Admin section. You don't need to set up a webserver for development, the webserver that can be started via nominatim serve is sufficient.

If you want to run Nominatim in a VM via Vagrant, use the default ubuntu24 setup. Vagrant's libvirt provider runs out-of-the-box under Ubuntu. You also need to install an NFS daemon to enable directory sharing between host and guest. The following packages should get you started:

sudo apt install vagrant vagrant-libvirt libvirt-daemon nfs-kernel-server

Prerequisites for testing and documentation🔗

The Nominatim test suite consists of behavioural tests (using pytest-bdd) and unit tests (using pytest). It has the following additional requirements:

For testing the Python search frontend, you need to install extra dependencies depending on your choice of webserver framework:

The documentation is built with mkdocs:

Installing prerequisites on Ubuntu/Debian🔗

The Python tools should always be run with the most recent version. The easiest way, to handle these Python dependencies is to run your development from within a virtual environment.

sudo apt install libsqlite3-mod-spatialite osm2pgsql \
                 postgresql-postgis postgresql-postgis-scripts \
                 pkg-config libicu-dev virtualenv

To set up the virtual environment with all necessary packages run:

virtualenv ~/nominatim-dev-venv
~/nominatim-dev-venv/bin/pip install\
    psutil 'psycopg[binary]' PyICU SQLAlchemy \
    python-dotenv jinja2 pyYAML \
    mkdocs 'mkdocstrings[python]' mkdocs-gen-files \
    pytest pytest-asyncio pytest-bdd flake8 \
    types-jinja2 types-markupsafe types-psutil types-psycopg2 \
    types-pygments types-pyyaml types-requests types-ujson \
    types-urllib3 typing-extensions unicorn falcon starlette \
    uvicorn mypy osmium aiosqlite

Now enter the virtual environment whenever you want to develop:

. ~/nominatim-dev-venv/bin/activate

Running Nominatim during development🔗

The source code for Nominatim can be found in the src directory and can be run in-place. The source directory features a special script nominatim-cli.py which does the same as the installed 'nominatim' binary but executes against the code in the source tree. For example:

me@machine:~$ cd Nominatim
me@machine:~Nominatim$ ./nominatim-cli.py --version
Nominatim version 4.4.99-1

Make sure you have activated the virtual environment holding all necessary dependencies.

Executing Tests🔗

All tests are located in the /test directory.

To run all tests, run make from the source root:

make tests

There are also make targets for executing only parts of the test suite. For example to run linting only use:

make lint

The possible testing targets are: mypy, lint, pytest, bdd.

For more information about the structure of the tests and how to change and extend the test suite, see the Testing chapter.

Documentation Pages🔗

The Nominatim documentation is built using the MkDocs static site generation framework. The master branch is automatically deployed every night on https://nominatim.org/release-docs/develop/

To build the documentation run

make doc

For local testing, you can start webserver:

build> make serve-doc
[server:296] Serving on http://127.0.0.1:8000
[handlers:62] Start watching changes

If you develop inside a Vagrant virtual machine, use a port that is forwarded to your host:

build> mkdocs serve --dev-addr 0.0.0.0:8088
[server:296] Serving on http://0.0.0.0:8088
[handlers:62] Start watching changes