]> git.openstreetmap.org Git - nominatim.git/blob - docs/admin/Setup-Nominatim-UI.md
Merge remote-tracking branch 'upstream/master'
[nominatim.git] / 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.