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