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