docs/admin/Deployment-Python.md

   1 # Deploying the Nominatim Python frontend
   2
   3 The Nominatim can be run as a Python-based web application. You have the
   4 choice between [Falcon](https://falcon.readthedocs.io/en/stable/)
   5 and [Starlette](https://www.starlette.io/) as the ASGI framework.
   6
   7 This section gives a quick overview on how to configure Nginx to server
   8 Nominatim. Please refer to the documentation of
   9 [Nginx](https://nginx.org/en/docs/) for background information on how to configure it.
  10
  11 !!! Note
  12     Throughout this page, we assume that your Nominatim project directory is
  13     located in `/srv/nominatim-project` and that you have installed Nominatim
  14     using the default installation prefix `/usr/local`. If you have put it
  15     somewhere else, you need to adjust the commands and configuration
  16     accordingly.
  17
  18     We further assume that your web server runs as user `www-data`. Older
  19     versions of CentOS may still use the user name `apache`. You also need
  20     to adapt the instructions in this case.
  21
  22 ### Installing the required packages
  23
  24 The recommended way to deploy Python ASGI application is to run
  25 the ASGI runner (uvicorn)[https://uvicorn.org/]
  26 together with (gunicorn)[https://gunicorn.org/] HTTP server. We use
  27 Falcon here as the web framework.
  28
  29 Create a virtual environment for the Python packages and install the necessary
  30 dependencies:
  31
  32 ``` sh
  33 sudo apt install virtualenv
  34 virtualenv /srv/nominatim-venv
  35 /srv/nominatim-venv/bin/pip install SQLAlchemy PyICU psycopg[binary]\
  36    psycopg2-binary python-dotenv PyYAML falcon uvicorn gunicorn
  37 ```
  38
  39 ### Setting up Nominatim as a systemd job
  40
  41 Next you need to set up the application that serves Nominatim. This is
  42 easiest done with a systemd job.
  43
  44 Create the following file `/etc/systemd/system/nominatim.service`:
  45
  46 ``` systemd
  47 [Unit]
  48 Description=Nominatim running as a gunicorn application
  49 After=network.target
  50 Requires=nominatim.socket
  51
  52 [Service]
  53 Type=simple
  54 Environment="PYTHONPATH=/usr/local/lib/nominatim/lib-python/"
  55 User=www-data
  56 Group=www-data
  57 WorkingDirectory=/srv/nominatim-project
  58 ExecStart=/srv/nominatim-venv/bin/gunicorn -b unix:/run/nominatim.sock -w 14 -k uvicorn.workers.UvicornWorker nominatim.server.falcon.server:run_wsgi
  59 ExecReload=/bin/kill -s HUP $MAINPID
  60 StandardOutput=append:/ssd/nominatim/log/gunicorn.log
  61 StandardError=inherit
  62 PrivateTmp=true
  63 TimeoutStopSec=5
  64 KillMode=mixed
  65
  66 [Install]
  67 WantedBy=multi-user.target
  68 ```
  69
  70 Make the new service known to systemd and start it:
  71
  72 ``` sh
  73 sudo systemctl daemon-reload
  74 sudo systemctl enable nominatim
  75 sudo systemctl start nominatim
  76 ```
  77
  78 This sets the service up, so that Nominatim is automatically started
  79 on reboot.
  80
  81 ### Configuring nginx
  82
  83 To make the service available to the world, you need to proxy it through
  84 nginx. Add the following definition to the default configuration:
  85
  86 ``` nginx
  87 upstream nominatim_service {
  88   server unix:/run/nominatim.sock fail_timeout=0;
  89 }
  90
  91 server {
  92     listen 80;
  93     listen [::]:80;
  94
  95     root /var/www/html;
  96     index /search;
  97
  98     location / {
  99             proxy_set_header Host $http_host;
 100             proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 101             proxy_set_header X-Forwarded-Proto $scheme;
 102             proxy_redirect off;
 103             proxy_pass http://nominatim_service;
 104     }
 105 }
 106 ```
 107
 108 Reload nginx with
 109
 110 ```
 111 sudo systemctl reload nginx
 112 ```
 113
 114 and you should be able to see the status of your server under
 115 `http://localhost/status`.