docs/admin/Deployment.md

   1 # Deploying Nominatim
   2
   3 The Nominatim API is implemented as a PHP application. The `website/` directory
   4 in the project directory contains the configured website. You can serve this
   5 in a production environment with any web server that is capable to run
   6 PHP scripts.
   7
   8 This section gives a quick overview on how to configure Apache and Nginx to
   9 serve Nominatim. It is not meant as a full system administration guide on how
  10 to run a web service. Please refer to the documentation of
  11 [Apache](http://httpd.apache.org/docs/current/) and
  12 [Nginx](https://nginx.org/en/docs/)
  13 for background information on configuring the services.
  14
  15 !!! Note
  16     Throughout this page, we assume that your Nominatim project directory is
  17     located in `/srv/nominatim-project` and that you have installed Nominatim
  18     using the default installation prefix `/usr/local`. If you have put it
  19     somewhere else, you need to adjust the commands and configuration
  20     accordingly.
  21
  22     We further assume that your web server runs as user `www-data`. Older
  23     versions of CentOS may still use the user name `apache`. You also need
  24     to adapt the instructions in this case.
  25
  26 ## Making the website directory accessible
  27
  28 You need to make sure that the `website` directory is accessible for the
  29 web server user. You can check that the permissions are correct by accessing
  30 on of the php files as the web server user:
  31
  32 ``` sh
  33 sudo -u www-data head -n 1 /srv/nominatim-project/website/search.php
  34 ```
  35
  36 If this shows a permission error, then you need to adapt the permissions of
  37 each directory in the path so that it is executable for `www-data`.
  38
  39 If you have SELinux enabled, further adjustments may be necessary to give the
  40 web server access. At a minimum the following SELinux labelling should be done
  41 for Nominatim:
  42
  43 ``` sh
  44 sudo semanage fcontext -a -t httpd_sys_content_t "/usr/local/nominatim/lib/lib-php(/.*)?"
  45 sudo semanage fcontext -a -t httpd_sys_content_t "/srv/nominatim-project/website(/.*)?"
  46 sudo semanage fcontext -a -t lib_t "/srv/nominatim-project/module/nominatim.so"
  47 sudo restorecon -R -v /usr/local/lib/nominatim
  48 sudo restorecon -R -v /srv/nominatim-project
  49 ```
  50
  51 ## Nominatim with Apache
  52
  53 ### Installing the required packages
  54
  55 With Apache you can use the PHP module to run Nominatim.
  56
  57 Under Ubuntu/Debian install them with:
  58
  59 ``` sh
  60 sudo apt install apache2 libapache2-mod-php
  61 ```
  62
  63 ### Configuring Apache
  64
  65 Make sure your Apache configuration contains the required permissions for the
  66 directory and create an alias:
  67
  68 ``` apache
  69 <Directory "/srv/nominatim-project/website">
  70   Options FollowSymLinks MultiViews
  71   AddType text/html   .php
  72   DirectoryIndex search.php
  73   Require all granted
  74 </Directory>
  75 Alias /nominatim /srv/nominatim-project/website
  76 ```
  77
  78 After making changes in the apache config you need to restart apache.
  79 The website should now be available on `http://localhost/nominatim`.
  80
  81 ## Nominatim with Nginx
  82
  83 ### Installing the required packages
  84
  85 Nginx has no built-in PHP interpreter. You need to use php-fpm as a deamon for
  86 serving PHP cgi.
  87
  88 On Ubuntu/Debian install nginx and php-fpm with:
  89
  90 ``` sh
  91 sudo apt install nginx php-fpm
  92 ```
  93
  94 ### Configure php-fpm and Nginx
  95
  96 By default php-fpm listens on a network socket. If you want it to listen to a
  97 Unix socket instead, change the pool configuration
  98 (`/etc/php/<php version>/fpm/pool.d/www.conf`) as follows:
  99
 100 ``` ini
 101 ; Replace the tcp listener and add the unix socket
 102 listen = /var/run/php-fpm.sock
 103
 104 ; Ensure that the daemon runs as the correct user
 105 listen.owner = www-data
 106 listen.group = www-data
 107 listen.mode = 0666
 108 ```
 109
 110 Tell nginx that php files are special and to fastcgi_pass to the php-fpm
 111 unix socket by adding the location definition to the default configuration.
 112
 113 ``` nginx
 114 root /srv/nominatim-project/website;
 115 index search.php;
 116 location / {
 117     try_files $uri $uri/ @php;
 118 }
 119
 120 location @php {
 121     fastcgi_param SCRIPT_FILENAME "$document_root$uri.php";
 122     fastcgi_param PATH_TRANSLATED "$document_root$uri.php";
 123     fastcgi_param QUERY_STRING    $args;
 124     fastcgi_pass unix:/var/run/php-fpm.sock;
 125     fastcgi_index index.php;
 126     include fastcgi_params;
 127 }
 128
 129 location ~ [^/]\.php(/|$) {
 130     fastcgi_split_path_info ^(.+?\.php)(/.*)$;
 131     if (!-f $document_root$fastcgi_script_name) {
 132         return 404;
 133     }
 134     fastcgi_pass unix:/var/run/php-fpm.sock;
 135     fastcgi_index search.php;
 136     include fastcgi.conf;
 137 }
 138 ```
 139
 140 Restart the nginx and php-fpm services and the website should now be available
 141 at `http://localhost/`.
 142
 143 ## Nominatim with other webservers
 144
 145 Users have created instructions for other webservers:
 146
 147 * [Caddy](https://github.com/osm-search/Nominatim/discussions/2580)
 148