docs/admin/Deployment-PHP.md

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