Nominatim/docs/admin/Setup-Nominatim-UI.md

Setting up the Nominatim UI

Nominatim is a search API, it does not provide a website interface on its own. nominatim-ui offers a small website for testing your setup and inspecting the database content.

This section provides a quick start how to use nominatim-ui with your installation. For more details, please also have a look at the README of nominatim-ui.

Installing nominatim-ui

We provide regular releases of nominatim-ui that contain the packaged website. They do not need any special installation. Just download, configure and run it. Grab the latest release from nominatim-ui's Github release page and unpack it. You can use nominatim-ui-x.x.x.tar.gz or nominatim-ui-x.x.x.zip.

Next you need to adapt the UI to your installation. Custom settings need to be put into dist/theme/config.theme.js. At a minimum you need to set Nominatim_API_Endpoint to point to your Nominatim installation:

cd nominatim-ui
echo "Nominatim_Config.Nominatim_API_Endpoint='https://myserver.org/nominatim/';" > dist/theme/config.theme.js

For the full set of available settings, have a look at dist/config.defaults.js.

Then you can just test it locally by spinning up a webserver in the dist directory. For example, with Python:

cd nominatim-ui/dist
python3 -m http.server 8765

The website is now available at http://localhost:8765.

Forwarding searches to nominatim-ui

Nominatim used to provide the search interface directly by itself when format=html was requested. For all endpoints except for /reverse and /lookup this even used to be the default.

The following section describes how to set up Apache or nginx, so that your users are forwarded to nominatim-ui when they go to URL that formerly presented the UI.

Setting up forwarding in Nginx

First of all make nominatim-ui available under /ui on your webserver:

server {

    # Here is the Nominatim setup as described in the Installation section

    location /ui/ {
        alias <full path to the nominatim-ui directory>/dist/;
        index index.html;
    }
}

Now we need to find out if a URL should be forwarded to the UI. Add the following map commands outside the server section:

# Inspect the format parameter in the query arguments. We are interested
# if it is set to html or something else or if it is missing completely.
map $args $format {
    default                  default;
    ~(^|&)format=html(&|$)   html;
    ~(^|&)format=            other;
}

# Determine from the URI and the format parameter above if forwarding is needed.
map $uri/$format $forward_to_ui {
    default               1;   # The default is to forward.
    ~^/ui                 0;   # If the URI point to the UI already, we are done.
    ~/other$              0;   # An explicit non-html format parameter. No forwarding.
    ~/reverse.*/default   0;   # Reverse and lookup assume xml format when
    ~/lookup.*/default    0;   #   no format parameter is given. No forwarding.
}

The $forward_to_ui parameter can now be used to conditionally forward the calls:

# When no endpoint is given, default to search.
# Need to add a rewrite so that the rewrite rules below catch it correctly.
rewrite ^/$ /search;

location @php {
    # fastcgi stuff..
    if ($forward_to_ui) {
        rewrite ^(/[^/]*) https://yourserver.com/ui$1.html redirect;
    }
}

location ~ [^/]\.php(/|$) {
    # fastcgi stuff..
    if ($forward_to_ui) {
        rewrite (.*).php https://yourserver.com/ui$1.html redirect;
    }
}

!!! warning Be aware that the rewrite commands are slightly different for URIs with and without the .php suffix.

Reload nginx and the UI should be available.

Setting up forwarding in Apache

First of all make nominatim-ui available in the ui/ subdirectory where Nominatim is installed. For example, given you have set up an alias under nominatim like this:

Alias /nominatim /home/vagrant/build/website

you need to insert the following rules for nominatim-ui before that alias:

<Directory "/home/vagrant/nominatim-ui/dist">
  DirectoryIndex search.html
  Require all granted
</Directory>

Alias /nominatim/ui /home/vagrant/nominatim-ui/dist

Replace /home/vagrant/nominatim-ui with the directory where you have cloned nominatim-ui.

!!! important The alias for nominatim-ui must come before the alias for the Nominatim website directory.

To set up forwarding, the Apache rewrite module is needed. Enable it with:

sudo a2enmod rewrite

Then add rewrite rules to the Directory directive of the Nominatim website directory like this:

<Directory "/home/vagrant/build/website">
  Options FollowSymLinks MultiViews
  AddType text/html   .php
  Require all granted

  RewriteEngine On

  # This must correspond to the URL where nominatim can be found.
  RewriteBase "/nominatim/"

  # If no endpoint is given, then use search.
  RewriteRule ^(/|$)   "search.php"

  # If format-html is explicitly requested, forward to the UI.
  RewriteCond %{QUERY_STRING} "format=html"
  RewriteRule ^([^/]+)(.php)? ui/$1.html [R,END]

  # If no format parameter is there then forward anything
  # but /reverse and /lookup to the UI.
  RewriteCond %{QUERY_STRING} "!format="
  RewriteCond %{REQUEST_URI}  "!/lookup"
  RewriteCond %{REQUEST_URI}  "!/reverse"
  RewriteRule ^([^/]+)(.php)? ui/$1.html [R,END]
</Directory>

Restart Apache and the UI should be available.