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 behave) and
  29 unit tests (using pytest). It has the following additional requirements:
  30
  31 * [behave test framework](https://behave.readthedocs.io) >= 1.2.6
  32 * [flake8](https://flake8.pycqa.org/en/stable/) (CI always runs the latest version from pip)
  33 * [mypy](http://mypy-lang.org/) (plus typing information for external libs)
  34 * [Python Typing Extensions](https://github.com/python/typing_extensions) (for Python < 3.9)
  35 * [pytest](https://pytest.org)
  36 * [pytest-asyncio](https://pytest-asyncio.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 Please be aware that tests always run against the globally installed
  52 osm2pgsql, so you need to have this set up. If you want to test against
  53 the vendored version of osm2pgsql, you need to set the PATH accordingly.
  54
  55 ### Installing prerequisites on Ubuntu/Debian
  56
  57 The Python tools should always be run with the most recent version.
  58 The easiest way, to handle these Python dependencies is to run your
  59 development from within a virtual environment.
  60
  61 ```sh
  62 sudo apt install libsqlite3-mod-spatialite osm2pgsql \
  63                  postgresql-postgis postgresql-postgis-scripts \
  64                  pkg-config libicu-dev virtualenv
  65 ```
  66
  67 To set up the virtual environment with all necessary packages run:
  68
  69 ```sh
  70 virtualenv ~/nominatim-dev-venv
  71 ~/nominatim-dev-venv/bin/pip install\
  72     psutil psycopg[binary] PyICU SQLAlchemy \
  73     python-dotenv jinja2 pyYAML datrie behave \
  74     mkdocs mkdocstrings mkdocs-gen-files pytest pytest-asyncio flake8 \
  75     types-jinja2 types-markupsafe types-psutil types-psycopg2 \
  76     types-pygments types-pyyaml types-requests types-ujson \
  77     types-urllib3 typing-extensions unicorn falcon starlette \
  78     uvicorn mypy osmium aiosqlite
  79 ```
  80
  81 Now enter the virtual environment whenever you want to develop:
  82
  83 ```sh
  84 . ~/nominatim-dev-venv/bin/activate
  85 ```
  86
  87 ### Running Nominatim during development
  88
  89 The source code for Nominatim can be found in the `src` directory and can
  90 be run in-place. The source directory features a special script
  91 `nominatim-cli.py` which does the same as the installed 'nominatim' binary
  92 but executes against the code in the source tree. For example:
  93
  94 ```
  95 me@machine:~$ cd Nominatim
  96 me@machine:~Nominatim$ ./nominatim-cli.py --version
  97 Nominatim version 4.4.99-1
  98 ```
  99
 100 Make sure you have activated the virtual environment holding all
 101 necessary dependencies.
 102
 103 ## Executing Tests
 104
 105 All tests are located in the `/test` directory.
 106
 107 To run all tests, run make from the source root:
 108
 109 ```sh
 110 make tests
 111 ```
 112
 113 There are also make targets for executing only parts of the test suite.
 114 For example to run linting only use:
 115
 116 ```sh
 117 make lint
 118 ```
 119
 120 The possible testing targets are: mypy, lint, pytest, bdd.
 121
 122 For more information about the structure of the tests and how to change and
 123 extend the test suite, see the [Testing chapter](Testing.md).
 124
 125 ## Documentation Pages
 126
 127 The [Nominatim documentation](https://nominatim.org/release-docs/develop/) is
 128 built using the [MkDocs](https://www.mkdocs.org/) static site generation
 129 framework. The master branch is automatically deployed every night on
 130 [https://nominatim.org/release-docs/develop/](https://nominatim.org/release-docs/develop/)
 131
 132 To build the documentation run
 133
 134 ```
 135 make doc
 136 ```
 137
 138
 139 For local testing, you can start webserver:
 140
 141 ```
 142 build> make serve-doc
 143 [server:296] Serving on http://127.0.0.1:8000
 144 [handlers:62] Start watching changes
 145 ```
 146
 147 If you develop inside a Vagrant virtual machine, use a port that is forwarded
 148 to your host:
 149
 150 ```
 151 build> mkdocs serve --dev-addr 0.0.0.0:8088
 152 [server:296] Serving on http://0.0.0.0:8088
 153 [handlers:62] Start watching changes
 154 ```