From 84403b47cbdf3487dfcc6dd690e85bb04b6f3ccf Mon Sep 17 00:00:00 2001 From: Sarah Hoffmann Date: Sat, 13 Jun 2020 20:06:01 +0200 Subject: [PATCH] add usage docs for nominatim-ui Includes migration guides for Apache and nginx. --- docs/admin/Setup-Nominatim-UI.md | 180 +++++++++++++++++++++++++++++++ docs/mkdocs.yml | 1 + 2 files changed, 181 insertions(+) create mode 100644 docs/admin/Setup-Nominatim-UI.md diff --git a/docs/admin/Setup-Nominatim-UI.md b/docs/admin/Setup-Nominatim-UI.md new file mode 100644 index 00000000..818ea408 --- /dev/null +++ b/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 /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: + +``` + + DirectoryIndex search.html + Require all granted + + +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 + + 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] + +``` + +Restart Apache and the UI should be available. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 88663f8b..16a67538 100644 --- a/docs/mkdocs.yml +++ b/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'