Deploying Nominatim

The Nominatim API is implemented as a PHP application. The website/ directory in the project directory contains the configured website. You can serve this in a production environment with any web server that is capable to run PHP scripts.

This section gives a quick overview on how to configure Apache and Nginx to serve Nominatim. It is not meant as a full system administration guide on how to run a web service. Please refer to the documentation of Apache and Nginx for background information on configuring the services.

Making the website directory accessible

You need to make sure that the website directory is accessible for the web server user. You can check that the permissions are correct by accessing on of the php files as the web server user:

sudo -u www-data head -n 1 /srv/nominatim-project/website/search.php

If this shows a permission error, then you need to adapt the permissions of each directory in the path so that it is executable for www-data.

If you have SELinux enabled, further adjustments may be necessary to give the web server access. At a minimum the following SELinux labelling should be done for Nominatim:

sudo semanage fcontext -a -t httpd_sys_content_t "/usr/local/nominatim/lib/lib-php(/.*)?"
sudo semanage fcontext -a -t httpd_sys_content_t "/srv/nominatim-project/website(/.*)?"
sudo semanage fcontext -a -t lib_t "/srv/nominatim-project/module/nominatim.so"
sudo restorecon -R -v /usr/local/lib/nominatim
sudo restorecon -R -v /srv/nominatim-project

Nominatim with Apache

Installing the required packages

With Apache you can use the PHP module to run Nominatim.

Under Ubuntu/Debian install them with:

sudo apt install apache2 libapache2-mod-php

Configuring Apache

Make sure your Apache configuration contains the required permissions for the directory and create an alias:

<Directory "/srv/nominatim-project/website">
  Options FollowSymLinks MultiViews
  AddType text/html   .php
  DirectoryIndex search.php
  Require all granted
</Directory>
Alias /nominatim /srv/nominatim-project/website

After making changes in the apache config you need to restart apache. The website should now be available on http://localhost/nominatim.

Nominatim with Nginx

Installing the required packages

Nginx has no built-in PHP interpreter. You need to use php-fpm as a deamon for serving PHP cgi.

On Ubuntu/Debian install nginx and php-fpm with:

sudo apt install nginx php-fpm

Configure php-fpm and Nginx

By default php-fpm listens on a network socket. If you want it to listen to a Unix socket instead, change the pool configuration (/etc/php/<php version>/fpm/pool.d/www.conf) as follows:

; Replace the tcp listener and add the unix socket
listen = /var/run/php-fpm.sock

; Ensure that the daemon runs as the correct user
listen.owner = www-data
listen.group = www-data
listen.mode = 0666

Tell nginx that php files are special and to fastcgi_pass to the php-fpm unix socket by adding the location definition to the default configuration.

root /srv/nominatim-project/website;
index search.php;
location / {
    try_files $uri $uri/ @php;
}

location @php {
    fastcgi_param SCRIPT_FILENAME "$document_root$uri.php";
    fastcgi_param PATH_TRANSLATED "$document_root$uri.php";
    fastcgi_param QUERY_STRING    $args;
    fastcgi_pass unix:/var/run/php-fpm.sock;
    fastcgi_index index.php;
    include fastcgi_params;
}

location ~ [^/]\.php(/|$) {
    fastcgi_split_path_info ^(.+?\.php)(/.*)$;
    if (!-f $document_root$fastcgi_script_name) {
        return 404;
    }
    fastcgi_pass unix:/var/run/php-fpm.sock;
    fastcgi_index search.php;
    include fastcgi.conf;
}

Restart the nginx and php-fpm services and the website should now be available at http://localhost/.