]> git.openstreetmap.org Git - nominatim.git/blob - docs/admin/Deployment.md
docs: move webserver installation into separate chapter
[nominatim.git] / docs / admin / Deployment.md
1 # Deploying Nominatim
2
3 The Nominatim API is implemented as a PHP application. The `website/` directory
4 in the build directory contains the configured website. You can serve this
5 in a production environment with any web server that is capable to run
6 PHP scripts.
7
8 This section gives a quick overview on how to configure Apache and Nginx to
9 serve Nominatim. It is not meant as a full system administration guide on how
10 to run a web service. Please refer to the documentation of
11 [Apache](http://httpd.apache.org/docs/current/) and
12 [Nginx](https://nginx.org/en/docs/)
13 for background information on configuring the services.
14
15 !!! Note
16     Throughout this page, we assume that your Nominatim build directory is
17     located in `/srv/nominatim/build` and the source code in
18     `/srv/nominatim/Nominatim`. If you have put it somewhere else, you
19     need to adjust the commands and configuration accordingly.
20
21     We further assume that your web server runs as user `www-data`. Older
22     versions of CentOS may still use the user name `apache`. You also need
23     to adapt the instructions in this case.
24
25 ## Making the website directory accessible
26
27 You need to make sure that the `website` directory is accessible for the
28 web server user. You can check that the permissions are correct by accessing
29 on of the php files as the web server user:
30
31 ``` sh
32 sudo -u www-data head -n 1 /srv/nominatim/build/website/search.php
33 ```
34
35 If this shows a permission error, then you need to adapt the permissions of
36 each directory in the path so that it is executable for `www-data`.
37
38 If you have SELinux enabled, further adjustments may be necessary to give the
39 web server access. At a minimum the following SELinux labelling should be done
40 for Nominatim:
41
42 ``` sh
43 sudo semanage fcontext -a -t httpd_sys_content_t "/srv/nominatim/Nominatim/(website|lib|settings)(/.*)?"
44 sudo semanage fcontext -a -t httpd_sys_content_t "/srv/nominatim/build/(website|settings)(/.*)?"
45 sudo semanage fcontext -a -t lib_t "/srv/nominatim/build/module/nominatim.so"
46 sudo restorecon -R -v /srv/nominatim/Nominatim
47 sudo restorecon -R -v /srv/nominatim/build
48 ```
49
50 ## Nominatim with Apache
51
52 ### Installing the required packages
53
54 With Apache you can use the PHP module to run Nominatim.
55
56 Under Ubuntu/Debian install them with:
57
58 ``` sh
59 sudo apt install apache2 libapache2-mod-php
60 ```
61
62 ### Configuring Apache
63
64 Make sure your Apache configuration contains the required permissions for the
65 directory and create an alias:
66
67 ``` apache
68 <Directory "/srv/nominatim/build/website">
69   Options FollowSymLinks MultiViews
70   AddType text/html   .php
71   DirectoryIndex search.php
72   Require all granted
73 </Directory>
74 Alias /nominatim /srv/nominatim/build/website
75 ```
76
77 After making changes in the apache config you need to restart apache.
78 The website should now be available on `http://localhost/nominatim`.
79
80 ## Nominatim with Nginx
81
82 ### Installing the required packages
83
84 Nginx has no built-in PHP interpreter. You need to use php-fpm as a deamon for
85 serving PHP cgi.
86
87 On Ubuntu/Debian install nginx and php-fpm with:
88
89 ``` sh
90 sudo apt install nginx php-fpm
91 ```
92
93 ### Configure php-fpm and Nginx
94
95 By default php-fpm listens on a network socket. If you want it to listen to a
96 Unix socket instead, change the pool configuration
97 (`/etc/php/<php version>/fpm/pool.d/www.conf`) as follows:
98
99 ``` ini
100 ; Replace the tcp listener and add the unix socket
101 listen = /var/run/php-fpm.sock
102
103 ; Ensure that the daemon runs as the correct user
104 listen.owner = www-data
105 listen.group = www-data
106 listen.mode = 0666
107 ```
108
109 Tell nginx that php files are special and to fastcgi_pass to the php-fpm
110 unix socket by adding the location definition to the default configuration.
111
112 ``` nginx
113 root /srv/nominatim/build/website;
114 index search.php;
115 location / {
116     try_files $uri $uri/ @php;
117 }
118
119 location @php {
120     fastcgi_param SCRIPT_FILENAME "$document_root$uri.php";
121     fastcgi_param PATH_TRANSLATED "$document_root$uri.php";
122     fastcgi_param QUERY_STRING    $args;
123     fastcgi_pass unix:/var/run/php-fpm.sock;
124     fastcgi_index index.php;
125     include fastcgi_params;
126 }
127
128 location ~ [^/]\.php(/|$) {
129     fastcgi_split_path_info ^(.+?\.php)(/.*)$;
130     if (!-f $document_root$fastcgi_script_name) {
131         return 404;
132     }
133     fastcgi_pass unix:/var/run/php-fpm.sock;
134     fastcgi_index search.php;
135     include fastcgi.conf;
136 }
137 ```
138
139 Restart the nginx and php-fpm services and the website should now be available
140 at `http://localhost/`.
141