add usage docs for nominatim-ui

Includes migration guides for Apache and nginx.

docs/admin/Setup-Nominatim-UI.md

@@ -0,0 +1,180 @@
+# Setting up the Nominatim UI
+
+Nominatim is a search API, it does not provide a website interface on its
+own. [nominatim-ui](https://github.com/osm-search/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](https://github.com/osm-search/nominatim-ui/blob/master/README.md).
+
+## Installing nominatim-ui
+
+nominatim-ui does not need any special installation, just download, configure
+and run it.
+
+Clone the source from github:
+
+    git clone https://github.com/osm-search/nominatim-ui
+
+Adapt the configuration `dist/config.js` to your needs. You need at least
+to change the `Nominatim_API_Endpoint` to point to your Nominatim installation.
+
+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:
+
+``` nginx
+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:
+
+``` nginx
+# 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 aboce 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 paramter. 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 ^(/[^/]*) http://nominatim.loar/ui$1.html redirect;
+    }
+}
+
+location ~ [^/]\.php(/|$) {
+    # fastcgi stuff..
+    if ($forward_to_ui) {
+        rewrite (.*).php http://nominatim.loar/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:
+
+``` apache
+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:
+
+``` sh
+sudo a2enmod rewrite
+```
+
+Then add rewrite rules to the `Directory` directive of the Nominatim website
+directory like this:
+
+``` apache
+<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 explicity requested, forward to the UI.
+  RewriteCond %{QUERY_STRING} "format=html"
+  RewriteRule ^([^/]+).php ui/$1.html [R,END]
+  # Same but .php suffix is missing.
+  RewriteCond %{QUERY_STRING} "format=html"
+  RewriteRule ^([^/]+) 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]
+  # Same but .php suffix is missing.
+  RewriteCond %{QUERY_STRING} "!format="
+  RewriteCond %{REQUEST_URI}  "!/lookup"
+  RewriteCond %{REQUEST_URI}  "!/reverse"
+  RewriteRule ^([^/]+) ui/$1.html [R,END]
+</Directory>
+```
+
+Restart Apache and the UI should be available.

docs/mkdocs.yml

@@ -17,6 +17,7 @@ pages:
     - 'Administration Guide':
         - 'Basic Installation': 'admin/Installation.md'
         - 'Importing and Updating' : 'admin/Import-and-Update.md'
+        - 'Nominatim UI'  : 'admin/Setup-Nominatim-UI.md'
         - 'Advanced Installations' : 'admin/Advanced-Installations.md'
         - 'Migration from older Versions' : 'admin/Migration.md'
         - 'Troubleshooting' : 'admin/Faq.md'