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