]> 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 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.