From: Sarah Hoffmann Date: Sun, 27 Aug 2023 19:27:16 +0000 (+0200) Subject: add deployment documentation for Python frontend X-Git-Tag: v4.3.0~13^2~4 X-Git-Url: https://git.openstreetmap.org./nominatim.git/commitdiff_plain/2c24ba6d2dd2d788ecf359eae23bad1e56ab62b2 add deployment documentation for Python frontend --- diff --git a/docs/admin/Deployment.md b/docs/admin/Deployment-PHP.md similarity index 99% rename from docs/admin/Deployment.md rename to docs/admin/Deployment-PHP.md index 8b635546..0e253d3d 100644 --- a/docs/admin/Deployment.md +++ b/docs/admin/Deployment-PHP.md @@ -1,4 +1,4 @@ -# Deploying Nominatim +# Deploying Nominatim using the PHP frontend The Nominatim API is implemented as a PHP application. The `website/` directory in the project directory contains the configured website. You can serve this diff --git a/docs/admin/Deployment-Python.md b/docs/admin/Deployment-Python.md new file mode 100644 index 00000000..fcbe9486 --- /dev/null +++ b/docs/admin/Deployment-Python.md @@ -0,0 +1,115 @@ +# Deploying the Nominatim Python frontend + +The Nominatim can be run as a Python-based web application. You have the +choice between [Falcon](https://falcon.readthedocs.io/en/stable/) +and [Starlette](https://www.starlette.io/) as the ASGI framework. + +This section gives a quick overview on how to configure Nginx to server +Nominatim. Please refer to the documentation of +[Nginx](https://nginx.org/en/docs/) for background information on how to configure it. + +!!! Note + Throughout this page, we assume that your Nominatim project directory is + located in `/srv/nominatim-project` and that you have installed Nominatim + using the default installation prefix `/usr/local`. If you have put it + somewhere else, you need to adjust the commands and configuration + accordingly. + + We further assume that your web server runs as user `www-data`. Older + versions of CentOS may still use the user name `apache`. You also need + to adapt the instructions in this case. + +### Installing the required packages + +The recommended way to deploy Python ASGI application is to run +the ASGI runner (uvicorn)[https://uvicorn.org/] +together with (gunicorn)[https://gunicorn.org/] HTTP server. We use +Falcon here as the web framework. + +Create a virtual environment for the Python packages and install the necessary +dependencies: + +``` sh +sudo apt install virtualenv +virtualenv /srv/nominatim-venv +/srv/nominatim-venv/bin/pip install SQLAlchemy PyICU psycopg[binary]\ + psycopg2-binary python-dotenv PyYAML falcon uvicorn gunicorn +``` + +### Setting up Nominatim as a systemd job + +Next you need to set up the application that serves Nominatim. This is +easiest done with a systemd job. + +Create the following file `/etc/systemd/system/nominatim.service`: + +``` systemd +[Unit] +Description=Nominatim running as a gunicorn application +After=network.target +Requires=nominatim.socket + +[Service] +Type=simple +Environment="PYTHONPATH=/usr/local/lib/nominatim/lib-python/" +User=www-data +Group=www-data +WorkingDirectory=/srv/nominatim-project +ExecStart=/srv/nominatim-venv/bin/gunicorn -b unix:/run/nominatim.sock -w 14 -k uvicorn.workers.UvicornWorker nominatim.server.falcon.server:run_wsgi +ExecReload=/bin/kill -s HUP $MAINPID +StandardOutput=append:/ssd/nominatim/log/gunicorn.log +StandardError=inherit +PrivateTmp=true +TimeoutStopSec=5 +KillMode=mixed + +[Install] +WantedBy=multi-user.target +``` + +Make the new service known to systemd and start it: + +``` sh +sudo systemctl daemon-reload +sudo systemctl enable nominatim +sudo systemctl start nominatim +``` + +This sets the service up, so that Nominatim is automatically started +on reboot. + +### Configuring nginx + +To make the service available to the world, you need to proxy it through +nginx. Add the following definition to the default configuration: + +``` nginx +upstream nominatim_service { + server unix:/run/nominatim.sock fail_timeout=0; +} + +server { + listen 80; + listen [::]:80; + + root /var/www/html; + index /search; + + location / { + proxy_set_header Host $http_host; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_redirect off; + proxy_pass http://nominatim_service; + } +} +``` + +Reload nginx with + +``` +sudo systemctl reload nginx +``` + +and you should be able to see the status of your server under +`http://localhost/status`. diff --git a/docs/admin/Import.md b/docs/admin/Import.md index d84a2376..62c12734 100644 --- a/docs/admin/Import.md +++ b/docs/admin/Import.md @@ -268,8 +268,9 @@ You can also run a search query, e.g. `http://localhost:8088/search.php?q=Berlin Note that search query is not supported for reverse-only imports. You can run a reverse query, e.g. `http://localhost:8088/reverse.php?lat=27.1750090510034&lon=78.04209025`. -To run Nominatim via webservers like Apache or nginx, please read the -[Deployment chapter](Deployment.md). +To run Nominatim via webservers like Apache or nginx, please continue reading +[Deploy the PHP frontend](Deployment-PHP.md) or +[Deploy the Python frontend](Deployment-Python.md). ## Adding search through category phrases diff --git a/docs/library/Introduction.md b/docs/library/Introduction.md deleted file mode 100644 index 3700bca2..00000000 --- a/docs/library/Introduction.md +++ /dev/null @@ -1,12 +0,0 @@ -# Nominatim Frontend as a Library - -The Nominatim search frontend can directly be used as a Python library in -scripts and applications. When you have imported your own Nominatim database, -then it is no longer necessary to run a full web service for it and access -the database through http requests. With the Nominatim library it is possible -to access all search functionality directly from your Python code. There are -also less constraints on the kinds of data that can be accessed. The library -allows to get access to more detailed information about the objects saved -in the database. - - diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index df68cda8..fb8ad072 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -22,7 +22,8 @@ nav: - 'Basic Installation': 'admin/Installation.md' - 'Import' : 'admin/Import.md' - 'Update' : 'admin/Update.md' - - 'Deploy' : 'admin/Deployment.md' + - 'Deploy (PHP frontend)' : 'admin/Deployment-PHP.md' + - 'Deploy (Python frontend)' : 'admin/Deployment-Python.md' - 'Nominatim UI' : 'admin/Setup-Nominatim-UI.md' - 'Advanced Installations' : 'admin/Advanced-Installations.md' - 'Maintenance' : 'admin/Maintenance.md' diff --git a/nominatim/api/results.py b/nominatim/api/results.py index 18df486f..0183f5b9 100644 --- a/nominatim/api/results.py +++ b/nominatim/api/results.py @@ -59,7 +59,7 @@ class SourceTable(enum.Enum): """ TIGER = 3 """ TIGER address data contains US addresses imported on the side, - see [Installing TIGER data](../../customize/Tiger.md). + see [Installing TIGER data](../customize/Tiger.md). TIGER address are also interpolations. The addresses always refer to a street from OSM data. The OSM id in the result refers to that street.