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 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 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`.