docs/admin/Deployment.md

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