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 !!! Note
  14     Throughout this page, we assume your Nominatim project directory is
  15     located in `/srv/nominatim-project`. If you have put it somewhere else,
  16     you need to adjust the commands and configuration accordingly.
  17
  18
  19 ### Installing the required packages
  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
  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 ASGI runner [uvicorn](https://uvicorn.org/)
  41 together with [gunicorn](https://gunicorn.org/) HTTP server. We use
  42 Falcon here as the web framework.
  43
  44 Add the necessary packages to your virtual environment:
  45
  46 ``` sh
  47 /srv/nominatim-venv/bin/pip install falcon uvicorn gunicorn
  48 ```
  49
  50 ### Setting up Nominatim as a systemd job
  51
  52 Next you need to set up the service that runs the Nominatim frontend. This is
  53 easiest done with a systemd job.
  54
  55 First you need to tell systemd to create a socket file to be used by
  56 hunicorn. Create the following file `/etc/systemd/system/nominatim.socket`:
  57
  58 ``` systemd
  59 [Unit]
  60 Description=Gunicorn socket for Nominatim
  61
  62 [Socket]
  63 ListenStream=/run/nominatim.sock
  64 SocketUser=www-data
  65
  66 [Install]
  67 WantedBy=multi-user.target
  68 ```
  69
  70 Now you can add the systemd service for Nominatim itself.
  71 Create the following file `/etc/systemd/system/nominatim.service`:
  72
  73 ``` systemd
  74 [Unit]
  75 Description=Nominatim running as a gunicorn application
  76 After=network.target
  77 Requires=nominatim.socket
  78
  79 [Service]
  80 Type=simple
  81 User=www-data
  82 Group=www-data
  83 WorkingDirectory=/srv/nominatim-project
  84 ExecStart=/srv/nominatim-venv/bin/gunicorn -b unix:/run/nominatim.sock -w 4 -k uvicorn.workers.UvicornWorker nominatim_api.server.falcon.server:run_wsgi
  85 ExecReload=/bin/kill -s HUP $MAINPID
  86 StandardOutput=append:/var/log/gunicorn-nominatim.log
  87 StandardError=inherit
  88 PrivateTmp=true
  89 TimeoutStopSec=5
  90 KillMode=mixed
  91
  92 [Install]
  93 WantedBy=multi-user.target
  94 ```
  95
  96 This sets up gunicorn with 4 workers (`-w 4` in ExecStart). Each worker runs
  97 its own Python process using
  98 [`NOMINATIM_API_POOL_SIZE`](../customize/Settings.md#nominatim_api_pool_size)
  99 connections to the database to serve requests in parallel.
 100
 101 Make the new services known to systemd and start it:
 102
 103 ``` sh
 104 sudo systemctl daemon-reload
 105 sudo systemctl enable nominatim.socket
 106 sudo systemctl start nominatim.socket
 107 sudo systemctl enable nominatim.service
 108 sudo systemctl start nominatim.service
 109 ```
 110
 111 This sets the service up, so that Nominatim is automatically started
 112 on reboot.
 113
 114 ### Configuring nginx
 115
 116 To make the service available to the world, you need to proxy it through
 117 nginx. Add the following definition to the default configuration:
 118
 119 ``` nginx
 120 upstream nominatim_service {
 121   server unix:/run/nominatim.sock fail_timeout=0;
 122 }
 123
 124 server {
 125     listen 80;
 126     listen [::]:80;
 127
 128     root /var/www/html;
 129     index /search;
 130
 131     location / {
 132             proxy_set_header Host $http_host;
 133             proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 134             proxy_set_header X-Forwarded-Proto $scheme;
 135             proxy_redirect off;
 136             proxy_pass http://nominatim_service;
 137     }
 138 }
 139 ```
 140
 141 Reload nginx with
 142
 143 ```
 144 sudo systemctl reload nginx
 145 ```
 146
 147 and you should be able to see the status of your server under
 148 `http://localhost/status`.