docs/admin/Setup-Nominatim-UI.md

   1 # Setting up the Nominatim UI
   2
   3 Nominatim is a search API, it does not provide a website interface on its
   4 own. [nominatim-ui](https://github.com/osm-search/nominatim-ui) offers a
   5 small website for testing your setup and inspecting the database content.
   6
   7 This section provides a quick start how to use nominatim-ui with your
   8 installation. For more details, please also have a look at the
   9 [README of nominatim-ui](https://github.com/osm-search/nominatim-ui/blob/master/README.md).
  10
  11 ## Installing nominatim-ui
  12
  13 We provide regular releases of nominatim-ui that contain the packaged website.
  14 They do not need any special installation. Just download, configure
  15 and run it. Grab the latest release from
  16 [nominatim-ui's Github release page](https://github.com/osm-search/nominatim-ui/releases)
  17 and unpack it. You can use `nominatim-ui-x.x.x.tar.gz` or `nominatim-ui-x.x.x.zip`.
  18
  19 Copy the example configuration into the right place:
  20
  21     cd nominatim-ui
  22     cp dist/config.example.js dist/config.js
  23
  24 Now adapt the configuration to your needs. You need at least
  25 to change the `Nominatim_API_Endpoint` to point to your Nominatim installation.
  26
  27 Then you can just test it locally by spinning up a webserver in the `dist`
  28 directory. For example, with Python:
  29
  30     cd nominatim-ui/dist
  31     python3 -m http.server 8765
  32
  33 The website is now available at `http://localhost:8765`.
  34
  35 ## Forwarding searches to nominatim-ui
  36
  37 Nominatim used to provide the search interface directly by itself when
  38 `format=html` was requested. For all endpoints except for `/reverse` and
  39 `/lookup` this even used to be the default.
  40
  41 The following section describes how to set up Apache or nginx, so that your
  42 users are forwarded to nominatim-ui when they go to URL that formerly presented
  43 the UI.
  44
  45 ### Setting up forwarding in Nginx
  46
  47 First of all make nominatim-ui available under `/ui` on your webserver:
  48
  49 ``` nginx
  50 server {
  51
  52     # Here is the Nominatim setup as described in the Installation section
  53
  54     location /ui/ {
  55         alias <full path to the nominatim-ui directory>/dist/;
  56         index index.html;
  57     }
  58 }
  59 ```
  60
  61 Now we need to find out if a URL should be forwarded to the UI. Add the
  62 following `map` commands *outside* the server section:
  63
  64 ``` nginx
  65 # Inspect the format parameter in the query arguments. We are interested
  66 # if it is set to html or something else or if it is missing completely.
  67 map $args $format {
  68     default                  default;
  69     ~(^|&)format=html(&|$)   html;
  70     ~(^|&)format=            other;
  71 }
  72
  73 # Determine from the URI and the format parameter above if forwarding is needed.
  74 map $uri/$format $forward_to_ui {
  75     default               1;   # The default is to forward.
  76     ~^/ui                 0;   # If the URI point to the UI already, we are done.
  77     ~/other$              0;   # An explicit non-html format parameter. No forwarding.
  78     ~/reverse.*/default   0;   # Reverse and lookup assume xml format when
  79     ~/lookup.*/default    0;   #   no format parameter is given. No forwarding.
  80 }
  81 ```
  82
  83 The `$forward_to_ui` parameter can now be used to conditionally forward the
  84 calls:
  85
  86 ```
  87 # When no endpoint is given, default to search.
  88 # Need to add a rewrite so that the rewrite rules below catch it correctly.
  89 rewrite ^/$ /search;
  90
  91 location @php {
  92     # fastcgi stuff..
  93     if ($forward_to_ui) {
  94         rewrite ^(/[^/]*) https://yourserver.com/ui$1.html redirect;
  95     }
  96 }
  97
  98 location ~ [^/]\.php(/|$) {
  99     # fastcgi stuff..
 100     if ($forward_to_ui) {
 101         rewrite (.*).php https://yourserver.com/ui$1.html redirect;
 102     }
 103 }
 104 ```
 105
 106 !!! warning
 107     Be aware that the rewrite commands are slightly different for URIs with and
 108     without the .php suffix.
 109
 110 Reload nginx and the UI should be available.
 111
 112 ### Setting up forwarding in Apache
 113
 114 First of all make nominatim-ui available in the `ui/` subdirectory where
 115 Nominatim is installed. For example, given you have set up an alias under
 116 `nominatim` like this:
 117
 118 ``` apache
 119 Alias /nominatim /home/vagrant/build/website
 120 ```
 121
 122 you need to insert the following rules for nominatim-ui before that alias:
 123
 124 ```
 125 <Directory "/home/vagrant/nominatim-ui/dist">
 126   DirectoryIndex search.html
 127   Require all granted
 128 </Directory>
 129
 130 Alias /nominatim/ui /home/vagrant/nominatim-ui/dist
 131 ```
 132
 133 Replace `/home/vagrant/nominatim-ui` with the directory where you have cloned
 134 nominatim-ui.
 135
 136 !!! important
 137     The alias for nominatim-ui must come before the alias for the Nominatim
 138     website directory.
 139
 140 To set up forwarding, the Apache rewrite module is needed. Enable it with:
 141
 142 ``` sh
 143 sudo a2enmod rewrite
 144 ```
 145
 146 Then add rewrite rules to the `Directory` directive of the Nominatim website
 147 directory like this:
 148
 149 ``` apache
 150 <Directory "/home/vagrant/build/website">
 151   Options FollowSymLinks MultiViews
 152   AddType text/html   .php
 153   Require all granted
 154
 155   RewriteEngine On
 156
 157   # This must correspond to the URL where nominatim can be found.
 158   RewriteBase "/nominatim/"
 159
 160   # If no endpoint is given, then use search.
 161   RewriteRule ^(/|$)   "search.php"
 162
 163   # If format-html is explicity requested, forward to the UI.
 164   RewriteCond %{QUERY_STRING} "format=html"
 165   RewriteRule ^([^/]+).php ui/$1.html [R,END]
 166   # Same but .php suffix is missing.
 167   RewriteCond %{QUERY_STRING} "format=html"
 168   RewriteRule ^([^/]+) ui/$1.html [R,END]
 169
 170   # If no format parameter is there then forward anything
 171   # but /reverse and /lookup to the UI.
 172   RewriteCond %{QUERY_STRING} "!format="
 173   RewriteCond %{REQUEST_URI}  "!/lookup"
 174   RewriteCond %{REQUEST_URI}  "!/reverse"
 175   RewriteRule ^([^/]+).php ui/$1.html [R,END]
 176   # Same but .php suffix is missing.
 177   RewriteCond %{QUERY_STRING} "!format="
 178   RewriteCond %{REQUEST_URI}  "!/lookup"
 179   RewriteCond %{REQUEST_URI}  "!/reverse"
 180   RewriteRule ^([^/]+) ui/$1.html [R,END]
 181 </Directory>
 182 ```
 183
 184 Restart Apache and the UI should be available.