docs/develop/Development-Environment.md

   1 # Setting up Nominatim for Development
   2
   3 This chapter gives an overview how to set up Nominatim for development
   4 and how to run tests.
   5
   6 !!! Important
   7     This guide assumes you develop under the latest version of Debian/Ubuntu.
   8     You can of course also use your favourite distribution. You just might have
   9     to adapt the commands below slightly, in particular the commands for
  10     installing additional software.
  11
  12 ## Installing Nominatim
  13
  14 The first step is to install Nominatim itself. Please follow the installation
  15 instructions in the [Admin section](../admin/Installation.md). You don't need
  16 to set up a webserver for development, the webserver that can be started
  17 via `nominatim serve` is sufficient.
  18
  19 If you want to run Nominatim in a VM via Vagrant, use the default `ubuntu24` setup.
  20 Vagrant's libvirt provider runs out-of-the-box under Ubuntu. You also need to
  21 install an NFS daemon to enable directory sharing between host and guest. The
  22 following packages should get you started:
  23
  24     sudo apt install vagrant vagrant-libvirt libvirt-daemon nfs-kernel-server
  25
  26 ## Prerequisites for testing and documentation
  27
  28 The Nominatim test suite consists of behavioural tests (using pytest-bdd) and
  29 unit tests (using pytest). It has the following additional requirements:
  30
  31 * [flake8](https://flake8.pycqa.org/en/stable/) (CI always runs the latest version from pip)
  32 * [mypy](http://mypy-lang.org/) (plus typing information for external libs)
  33 * [Python Typing Extensions](https://github.com/python/typing_extensions) (for Python < 3.9)
  34 * [pytest](https://pytest.org)
  35 * [pytest-asyncio](https://pytest-asyncio.readthedocs.io)
  36 * [pytest-bdd](https://pytest-bdd.readthedocs.io)
  37
  38 For testing the Python search frontend, you need to install extra dependencies
  39 depending on your choice of webserver framework:
  40
  41 * [httpx](https://www.python-httpx.org/) (Starlette only)
  42 * [asgi-lifespan](https://github.com/florimondmanca/asgi-lifespan) (Starlette only)
  43
  44 The documentation is built with mkdocs:
  45
  46 * [mkdocs](https://www.mkdocs.org/) >= 1.1.2
  47 * [mkdocstrings](https://mkdocstrings.github.io/) >= 0.25
  48 * [mkdocs-material](https://squidfunk.github.io/mkdocs-material/)
  49 * [mkdocs-gen-files](https://oprypin.github.io/mkdocs-gen-files/)
  50
  51
  52 ### Installing prerequisites on Ubuntu/Debian
  53
  54 The Python tools should always be run with the most recent version.
  55 The easiest way, to handle these Python dependencies is to run your
  56 development from within a virtual environment.
  57
  58 ```sh
  59 sudo apt install build-essential libsqlite3-mod-spatialite osm2pgsql \
  60                  postgresql-postgis postgresql-postgis-scripts \
  61                  pkg-config libicu-dev virtualenv
  62 ```
  63
  64 #### Using pip
  65
  66 Create a virtual environment and install all dependencies from the project's
  67 `pyproject.toml`:
  68 ```sh
  69 virtualenv ~/nominatim-dev-venv
  70 . ~/nominatim-dev-venv/bin/activate
  71 pip install --group dev .
  72 ```
  73
  74 This installs the two Nominatim packages (`nominatim-api`, `nominatim-db`)
  75 along with all development dependencies (tests, linting, type stubs, docs, serve).
  76
  77 To install runtime dependencies only:
  78 ```sh
  79 pip install .
  80 ```
  81
  82 #### Using uv
  83
  84 If you prefer, you can use [uv](https://docs.astral.sh/uv/) for a faster
  85 development setup. Install uv following the
  86 [official instructions](https://docs.astral.sh/uv/getting-started/installation/),
  87 then from the Nominatim source directory:
  88
  89 ```sh
  90 uv sync
  91 ```
  92
  93 This creates a virtual environment and installs all Python dependencies
  94 automatically. To run commands in the environment:
  95
  96 ```sh
  97 uv run nominatim --version
  98 uv run pytest test/python
  99 uv run make lint
 100 ```
 101
 102 ### Running Nominatim during development
 103
 104 The source code for Nominatim can be found in the `src` directory and can
 105 be run in-place. The source directory features a special script
 106 `nominatim-cli.py` which does the same as the installed 'nominatim' binary
 107 but executes against the code in the source tree. For example:
 108
 109 ```
 110 me@machine:~$ cd Nominatim
 111 me@machine:~Nominatim$ ./nominatim-cli.py --version
 112 Nominatim version 5.1.0-0
 113 ```
 114
 115 Make sure you have activated the virtual environment holding all
 116 necessary dependencies.
 117
 118 ## Executing Tests
 119
 120 All tests are located in the `/test` directory.
 121
 122 To run all tests, run make from the source root:
 123
 124 ```sh
 125 make tests
 126 ```
 127
 128 There are also make targets for executing only parts of the test suite.
 129 For example to run linting only use:
 130
 131 ```sh
 132 make lint
 133 ```
 134
 135 The possible testing targets are: mypy, lint, pytest, bdd.
 136
 137 For more information about the structure of the tests and how to change and
 138 extend the test suite, see the [Testing chapter](Testing.md).
 139
 140 ## Documentation Pages
 141
 142 The [Nominatim documentation](https://nominatim.org/release-docs/develop/) is
 143 built using the [MkDocs](https://www.mkdocs.org/) static site generation
 144 framework. The master branch is automatically deployed every night on
 145 [https://nominatim.org/release-docs/develop/](https://nominatim.org/release-docs/develop/)
 146
 147 To build the documentation run
 148
 149 ```
 150 make doc
 151 ```
 152
 153
 154 For local testing, you can start webserver:
 155
 156 ```
 157 build> make serve-doc
 158 [server:296] Serving on http://127.0.0.1:8000
 159 [handlers:62] Start watching changes
 160 ```
 161
 162 If you develop inside a Vagrant virtual machine, use a port that is forwarded
 163 to your host:
 164
 165 ```
 166 build> mkdocs serve --dev-addr 0.0.0.0:8088
 167 [server:296] Serving on http://0.0.0.0:8088
 168 [handlers:62] Start watching changes
 169 ```