docs/admin/Deployment-Python.md

   1 # Deploying the Nominatim Python frontend
   2
   3 Nominatim can be run as a Python-based
   4 [ASGI web application](https://asgi.readthedocs.io/en/latest/). You have the
   5 choice between [Falcon](https://falcon.readthedocs.io/en/stable/)
   6 and [Starlette](https://www.starlette.io/) as the ASGI framework.
   7
   8 This section gives a quick overview on how to configure Nginx to serve
   9 Nominatim. Please refer to the documentation of
  10 [Nginx](https://nginx.org/en/docs/) for background information on how
  11 to configure it.
  12
  13 ### Installing the required packages
  14
  15 !!! warning
  16     ASGI support in gunicorn requires at least version 25.0. If you need
  17     to work with an older version of gunicorn, please refer to
  18     [older Nominatim deployment documentation](https://nominatim.org/release-docs/5.2/admin/Deployment-Python/)
  19     to learn how to run gunicorn with uvicorn.
  20
  21 The Nominatim frontend is best run from its own virtual environment. If
  22 you have already created one for the database backend during the
  23 [installation](Installation.md#building-nominatim), you can use that. Otherwise
  24 create one now with:
  25
  26 ```sh
  27 sudo apt-get install virtualenv
  28 virtualenv /srv/nominatim-venv
  29 ```
  30
  31 The Nominatim frontend is contained in the 'nominatim-api' package. To
  32 install directly from the source tree run:
  33
  34 ```sh
  35 cd Nominatim
  36 /srv/nominatim-venv/bin/pip install packaging/nominatim-api
  37 ```
  38
  39 The recommended way to deploy a Python ASGI application is to run
  40 the [gunicorn](https://gunicorn.org/) HTTP server. We use
  41 Falcon here as the web framework.
  42
  43 Add the necessary packages to your virtual environment:
  44
  45 ``` sh
  46 /srv/nominatim-venv/bin/pip install falcon gunicorn
  47 ```
  48
  49 ### Setting up Nominatim as a systemd job
  50
  51 !!! Note
  52     These instructions assume your Nominatim project directory is
  53     located in `/srv/nominatim-project`. If you have put it somewhere else,
  54     you need to adjust the commands and configuration accordingly.
  55
  56 Next you need to set up the service that runs the Nominatim frontend. This is
  57 easiest done with a systemd job.
  58
  59 First you need to tell systemd to create a socket file to be used by
  60 gunicorn. Create the following file `/etc/systemd/system/nominatim.socket`:
  61
  62 ``` systemd
  63 [Unit]
  64 Description=Gunicorn socket for Nominatim
  65
  66 [Socket]
  67 ListenStream=/run/nominatim.sock
  68 SocketUser=www-data
  69
  70 [Install]
  71 WantedBy=multi-user.target
  72 ```
  73
  74 Now you can add the systemd service for Nominatim itself.
  75 Create the following file `/etc/systemd/system/nominatim.service`:
  76
  77 ``` systemd
  78 [Unit]
  79 Description=Nominatim running as a gunicorn application
  80 After=network.target
  81 Requires=nominatim.socket
  82
  83 [Service]
  84 Type=simple
  85 User=www-data
  86 Group=www-data
  87 WorkingDirectory=/srv/nominatim-project
  88 ExecStart=/srv/nominatim-venv/bin/gunicorn -b unix:/run/nominatim.sock -w 4 --worker-class asgi --protocol uwsgi --worker-connections 1000 "nominatim_api.server.falcon.server:run_wsgi()"
  89 ExecReload=/bin/kill -s HUP $MAINPID
  90 PrivateTmp=true
  91 TimeoutStopSec=5
  92 KillMode=mixed
  93
  94 [Install]
  95 WantedBy=multi-user.target
  96 ```
  97
  98 This sets up gunicorn with 4 workers (`-w 4` in ExecStart). Each worker runs
  99 its own Python process using
 100 [`NOMINATIM_API_POOL_SIZE`](../customize/Settings.md#nominatim_api_pool_size)
 101 connections to the database to serve requests in parallel. The parameter
 102 `--worker-connections` restricts how many requests gunicorn will queue for
 103 each worker. This can help distribute work better when the server is under
 104 high load.
 105
 106 Make the new services known to systemd and start it:
 107
 108 ``` sh
 109 sudo systemctl daemon-reload
 110 sudo systemctl enable nominatim.socket
 111 sudo systemctl start nominatim.socket
 112 sudo systemctl enable nominatim.service
 113 sudo systemctl start nominatim.service
 114 ```
 115
 116 This sets the service up so that Nominatim is automatically started
 117 on reboot.
 118
 119 ### Configuring nginx
 120
 121 To make the service available to the world, you need to proxy it through
 122 nginx. We use the binary uwsgi protocol to speed up communication
 123 between nginx and gunicorn. Add the following definition to the default
 124 configuration:
 125
 126 ``` nginx
 127 upstream nominatim_service {
 128   server unix:/run/nominatim.sock fail_timeout=0;
 129 }
 130
 131 server {
 132     listen 80;
 133     listen [::]:80;
 134
 135     root /var/www/html;
 136     index /search;
 137
 138     location / {
 139         uwsgi_pass nominatim_service;
 140         include uwsgi_params;
 141     }
 142 }
 143 ```
 144
 145 Reload nginx with
 146
 147 ```
 148 sudo systemctl reload nginx
 149 ```
 150
 151 and you should be able to see the status of your server under
 152 `http://localhost/status`.