]> 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 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   # Same but .php suffix is missing.
168   RewriteCond %{QUERY_STRING} "format=html"
169   RewriteRule ^([^/]+) ui/$1.html [R,END]
170
171   # If no format parameter is there then forward anything
172   # but /reverse and /lookup to the UI.
173   RewriteCond %{QUERY_STRING} "!format="
174   RewriteCond %{REQUEST_URI}  "!/lookup"
175   RewriteCond %{REQUEST_URI}  "!/reverse"
176   RewriteRule ^([^/]+).php ui/$1.html [R,END]
177   # Same but .php suffix is missing.
178   RewriteCond %{QUERY_STRING} "!format="
179   RewriteCond %{REQUEST_URI}  "!/lookup"
180   RewriteCond %{REQUEST_URI}  "!/reverse"
181   RewriteRule ^([^/]+) ui/$1.html [R,END]
182 </Directory>
183 ```
184
185 Restart Apache and the UI should be available.