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 the `/search` endpoint this even used
  40 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 a 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               0;  # no forwarding by default
  77     ~/search.*/default    1;  # Use this line only, if search should go to UI by default.
  78     ~/reverse.*/html      1;  # Forward API calls that UI supports, when
  79     ~/status.*/html       1;  #   format=html is explicitly requested.
  80     ~/search.*/html       1;
  81     ~/details.*/html      1;
  82 }
  83 ```
  84
  85 The `$forward_to_ui` parameter can now be used to conditionally forward the
  86 calls:
  87
  88 ``` nginx
  89 location / {
  90     if ($forward_to_ui) {
  91         rewrite ^(/[^/.]*) https://$http_host/ui$1.html redirect;
  92     }
  93
  94     # proxy_pass commands
  95 }
  96 ```
  97
  98 Reload nginx and the UI should be available.
  99
 100 ### Setting up forwarding in Apache
 101
 102 First of all make nominatim-ui available in the `ui/` subdirectory where
 103 Nominatim is installed. For example, given you have set up an alias under
 104 `nominatim` like this:
 105
 106 ``` apache
 107 Alias /nominatim /home/vagrant/build/website
 108 ```
 109
 110 you need to insert the following rules for nominatim-ui before that alias:
 111
 112 ```
 113 <Directory "/home/vagrant/nominatim-ui/dist">
 114   DirectoryIndex search.html
 115   Require all granted
 116 </Directory>
 117
 118 Alias /nominatim/ui /home/vagrant/nominatim-ui/dist
 119 ```
 120
 121 Replace `/home/vagrant/nominatim-ui` with the directory where you have cloned
 122 nominatim-ui.
 123
 124 !!! important
 125     The alias for nominatim-ui must come before the alias for the Nominatim
 126     website directory.
 127
 128 To set up forwarding, the Apache rewrite module is needed. Enable it with:
 129
 130 ``` sh
 131 sudo a2enmod rewrite
 132 ```
 133
 134 Then add rewrite rules to the `Directory` directive of the Nominatim website
 135 directory like this:
 136
 137 ``` apache
 138 <Directory "/home/vagrant/build/website">
 139   Options FollowSymLinks MultiViews
 140   AddType text/html   .php
 141   Require all granted
 142
 143   RewriteEngine On
 144
 145   # This must correspond to the URL where nominatim can be found.
 146   RewriteBase "/nominatim/"
 147
 148   # If no endpoint is given, then use search.
 149   RewriteRule ^(/|$)   "search"
 150
 151   # If format-html is explicitly requested, forward to the UI.
 152   RewriteCond %{QUERY_STRING} "format=html"
 153   RewriteRule ^([^/.]+) ui/$1.html [R,END]
 154
 155   # Optionally: if no format parameter is there then forward /search.
 156   RewriteCond %{QUERY_STRING} "!format="
 157   RewriteCond %{REQUEST_URI}  "/search"
 158   RewriteRule ^([^/.]+) ui/$1.html [R,END]
 159 </Directory>
 160 ```
 161
 162 Restart Apache and the UI should be available.