X-Git-Url: https://git.openstreetmap.org./nominatim.git/blobdiff_plain/2c24ba6d2dd2d788ecf359eae23bad1e56ab62b2..738e99ce71b165e9fddb3381ba683fb5fd9b7298:/docs/admin/Deployment-Python.md

diff --git a/docs/admin/Deployment-Python.md b/docs/admin/Deployment-Python.md
index fcbe9486..821a2c06 100644
--- a/docs/admin/Deployment-Python.md
+++ b/docs/admin/Deployment-Python.md
@@ -1,46 +1,73 @@
 # Deploying the Nominatim Python frontend
 
-The Nominatim can be run as a Python-based web application. You have the
+Nominatim can be run as a Python-based
+[ASGI web application](https://asgi.readthedocs.io/en/latest/). 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
+This section gives a quick overview on how to configure Nginx to serve
 Nominatim. Please refer to the documentation of
-[Nginx](https://nginx.org/en/docs/) for background information on how to configure it.
+[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.
+    Throughout this page, we assume your Nominatim project directory is
+    located in `/srv/nominatim-project`. 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
+The Nominatim frontend is best run from its own virtual environment. If
+you have already created one for the database backend during
+[installation](Installation.md#Building-Nominatim), you can use that. Otherwise
+create one now with:
+
+```sh
+sudo apt-get install virtualenv
+virtualenv /srv/nominatim-venv
+```
+
+The Nominatim frontend is contained in the 'nominatim-api' package. To
+install directly from the source tree run:
+
+```sh
+cd Nominatim
+/srv/nominatim-venv/bin/pip install packaging/nominatim-api
+```
+
+The recommended way to deploy a 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:
+Add the necessary packages to your virtual environment:
 
 ``` 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
+/srv/nominatim-venv/bin/pip install falcon uvicorn gunicorn
 ```
 
 ### Setting up Nominatim as a systemd job
 
-Next you need to set up the application that serves Nominatim. This is
+Next you need to set up the service that runs the Nominatim frontend. This is
 easiest done with a systemd job.
 
+First you need to tell systemd to create a socket file to be used by
+hunicorn. Create the following file `/etc/systemd/system/nominatim.socket`:
+
+``` systemd
+[Unit]
+Description=Gunicorn socket for Nominatim
+
+[Socket]
+ListenStream=/run/nominatim.sock
+SocketUser=www-data
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Now you can add the systemd service for Nominatim itself.
 Create the following file `/etc/systemd/system/nominatim.service`:
 
 ``` systemd
@@ -51,13 +78,12 @@ 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
+ExecStart=/srv/nominatim-venv/bin/gunicorn -b unix:/run/nominatim.sock -w 4 -k uvicorn.workers.UvicornWorker nominatim_api.server.falcon.server:run_wsgi
 ExecReload=/bin/kill -s HUP $MAINPID
-StandardOutput=append:/ssd/nominatim/log/gunicorn.log
+StandardOutput=append:/var/log/gunicorn-nominatim.log
 StandardError=inherit
 PrivateTmp=true
 TimeoutStopSec=5
@@ -67,12 +93,19 @@ KillMode=mixed
 WantedBy=multi-user.target
 ```
 
-Make the new service known to systemd and start it:
+This sets up gunicorn with 4 workers (`-w 4` in ExecStart). Each worker runs
+its own Python process using
+[`NOMINATIM_API_POOL_SIZE`](../customize/Settings.md#nominatim_api_pool_size)
+connections to the database to serve requests in parallel.
+
+Make the new services known to systemd and start it:
 
 ``` sh
 sudo systemctl daemon-reload
-sudo systemctl enable nominatim
-sudo systemctl start nominatim
+sudo systemctl enable nominatim.socket
+sudo systemctl start nominatim.socket
+sudo systemctl enable nominatim.service
+sudo systemctl start nominatim.service
 ```
 
 This sets the service up, so that Nominatim is automatically started