diff --git a/docs/admin/Deployment.md b/docs/admin/Deployment.md
new file mode 100644
index 00000000..9ef7f489
--- /dev/null
+++ b/docs/admin/Deployment.md
@@ -0,0 +1,141 @@
+# Deploying Nominatim
+
+The Nominatim API is implemented as a PHP application. The `website/` directory
+in the build directory contains the configured website. You can serve this
+in a production environment with any web server that is capable to run
+PHP scripts.
+
+This section gives a quick overview on how to configure Apache and Nginx to
+serve Nominatim. It is not meant as a full system administration guide on how
+to run a web service. Please refer to the documentation of
+[Apache](http://httpd.apache.org/docs/current/) and
+[Nginx](https://nginx.org/en/docs/)
+for background information on configuring the services.
+
+!!! Note
+ Throughout this page, we assume that your Nominatim build directory is
+ located in `/srv/nominatim/build` and the source code in
+ `/srv/nominatim/Nominatim`. If you have put it somewhere else, you
+ need to adjust the commands and configuration accordingly.
+
+ We further assume that your web server runs as user `www-data`. Older
+ versions of CentOS may still use the user name `apache`. You also need
+ to adapt the instructions in this case.
+
+## Making the website directory accessible
+
+You need to make sure that the `website` directory is accessible for the
+web server user. You can check that the permissions are correct by accessing
+on of the php files as the web server user:
+
+``` sh
+sudo -u www-data head -n 1 /srv/nominatim/build/website/search.php
+```
+
+If this shows a permission error, then you need to adapt the permissions of
+each directory in the path so that it is executable for `www-data`.
+
+If you have SELinux enabled, further adjustments may be necessary to give the
+web server access. At a minimum the following SELinux labelling should be done
+for Nominatim:
+
+``` sh
+sudo semanage fcontext -a -t httpd_sys_content_t "/srv/nominatim/Nominatim/(website|lib|settings)(/.*)?"
+sudo semanage fcontext -a -t httpd_sys_content_t "/srv/nominatim/build/(website|settings)(/.*)?"
+sudo semanage fcontext -a -t lib_t "/srv/nominatim/build/module/nominatim.so"
+sudo restorecon -R -v /srv/nominatim/Nominatim
+sudo restorecon -R -v /srv/nominatim/build
+```
+
+## Nominatim with Apache
+
+### Installing the required packages
+
+With Apache you can use the PHP module to run Nominatim.
+
+Under Ubuntu/Debian install them with:
+
+``` sh
+sudo apt install apache2 libapache2-mod-php
+```
+
+### Configuring Apache
+
+Make sure your Apache configuration contains the required permissions for the
+directory and create an alias:
+
+``` apache
+
+ Options FollowSymLinks MultiViews
+ AddType text/html .php
+ DirectoryIndex search.php
+ Require all granted
+
+Alias /nominatim /srv/nominatim/build/website
+```
+
+After making changes in the apache config you need to restart apache.
+The website should now be available on `http://localhost/nominatim`.
+
+## Nominatim with Nginx
+
+### Installing the required packages
+
+Nginx has no built-in PHP interpreter. You need to use php-fpm as a deamon for
+serving PHP cgi.
+
+On Ubuntu/Debian install nginx and php-fpm with:
+
+``` sh
+sudo apt install nginx php-fpm
+```
+
+### Configure php-fpm and Nginx
+
+By default php-fpm listens on a network socket. If you want it to listen to a
+Unix socket instead, change the pool configuration
+(`/etc/php//fpm/pool.d/www.conf`) as follows:
+
+``` ini
+; Replace the tcp listener and add the unix socket
+listen = /var/run/php-fpm.sock
+
+; Ensure that the daemon runs as the correct user
+listen.owner = www-data
+listen.group = www-data
+listen.mode = 0666
+```
+
+Tell nginx that php files are special and to fastcgi_pass to the php-fpm
+unix socket by adding the location definition to the default configuration.
+
+``` nginx
+root /srv/nominatim/build/website;
+index search.php;
+location / {
+ try_files $uri $uri/ @php;
+}
+
+location @php {
+ fastcgi_param SCRIPT_FILENAME "$document_root$uri.php";
+ fastcgi_param PATH_TRANSLATED "$document_root$uri.php";
+ fastcgi_param QUERY_STRING $args;
+ fastcgi_pass unix:/var/run/php-fpm.sock;
+ fastcgi_index index.php;
+ include fastcgi_params;
+}
+
+location ~ [^/]\.php(/|$) {
+ fastcgi_split_path_info ^(.+?\.php)(/.*)$;
+ if (!-f $document_root$fastcgi_script_name) {
+ return 404;
+ }
+ fastcgi_pass unix:/var/run/php-fpm.sock;
+ fastcgi_index search.php;
+ include fastcgi.conf;
+}
+```
+
+Restart the nginx and php-fpm services and the website should now be available
+at `http://localhost/`.
+
diff --git a/docs/admin/Import.md b/docs/admin/Import.md
index ded69293..334c1b75 100644
--- a/docs/admin/Import.md
+++ b/docs/admin/Import.md
@@ -187,7 +187,7 @@ enough RAM for PostgreSQL and osm2pgsql as mentioned above. If the system starts
swapping or you are getting out-of-memory errors, reduce the cache size or
even consider using a flatnode file.
-### Verify import finished
+### Verify the import
Run this script to verify all required tables and indices got created successfully.
@@ -197,9 +197,8 @@ Run this script to verify all required tables and indices got created successful
### Setting up the website
-Run the following command to set up the `website/settings-frontend.php`.
-These settings are used in website/*.php files. You can use the website only after this
-step is completed.
+Run the following command to set up the configuration file for the website
+`settings/settings-frontend.php`. These settings are used in website/*.php files.
```sh
./utils/setup.php --setup-website
@@ -207,6 +206,20 @@ step is completed.
!!! Note
This step is not necessary if you use `--all` option while setting up the DB.
+Now you can try out your installation by running:
+
+```sh
+make serve
+```
+
+This runs a small test server normally used for development. You can use it
+to verify that your installation is working. Go to
+`http://localhost:8088/status.php` and you should see the message `OK`.
+You can also run a search query, e.g. `http://localhost:8088/search.php?q=Berlin`.
+
+To run Nominatim via webservers like Apache or nginx, please read the
+[Deployment chapter](Deployment.md).
+
## Tuning the database
Accurate word frequency information for search terms helps PostgreSQL's query
@@ -247,8 +260,6 @@ entire US adds about 10GB to your database.
wget https://nominatim.org/data/tiger2019-nominatim-preprocessed.tar.gz
tar xf tiger2019-nominatim-preprocessed.tar.gz
- `data-source/overview.md` explains how the data got preprocessed.
-
2. Import the data into your Nominatim database:
./utils/setup.php --import-tiger-data
@@ -264,3 +275,6 @@ entire US adds about 10GB to your database.
```
+See the [developer's guide](../develop/data-sources.md#us-census-tiger) for more
+information on how the data got preprocessed.
+
diff --git a/docs/admin/Installation.md b/docs/admin/Installation.md
index bc97212e..b9c78004 100644
--- a/docs/admin/Installation.md
+++ b/docs/admin/Installation.md
@@ -43,7 +43,6 @@ For running Nominatim:
* [PHP](https://php.net) (7.0 or later)
* PHP-pgsql
* PHP-intl (bundled with PHP)
- * a webserver (apache or nginx are recommended)
For running continuous updates:
@@ -68,9 +67,7 @@ will help considerably to speed up import and queries.
Even on a well configured machine the import of a full planet takes
at least 2 days. Without SSDs 7-8 days are more realistic.
-## Setup of the server
-
-### PostgreSQL tuning
+## Tuning the PostgreSQL database
You might want to tune your PostgreSQL installation so that the later steps
make best use of your hardware. You should tune the following parameters in
@@ -110,82 +107,44 @@ Don't forget to reenable them after the initial import or you risk database
corruption.
-### Webserver setup
+## Downloading and building Nominatim
-The `website/` directory in the build directory contains the configured
-website. Include the directory into your webbrowser to serve php files
-from there.
+### Downloading the latest release
-#### Configure for use with Apache
+You can download the [latest release from nominatim.org](https://nominatim.org/downloads/).
+The release contains all necessary files. Just unpack it.
-Make sure your Apache configuration contains the required permissions for the
-directory and create an alias:
+### Downloading the latest development version
-``` apache
-
- Options FollowSymLinks MultiViews
- AddType text/html .php
- DirectoryIndex search.php
- Require all granted
-
-Alias /nominatim /srv/nominatim/build/website
+If you want to install latest development version from github, make sure to
+also check out the osm2pgsql subproject:
+
+```
+git clone --recursive git://github.com/openstreetmap/Nominatim.git
```
-`/srv/nominatim/build` should be replaced with the location of your
-build directory.
+The development version does not include the country grid. Download it separately:
-After making changes in the apache config you need to restart apache.
-The website should now be available on http://localhost/nominatim.
-
-#### Configure for use with Nginx
-
-Use php-fpm as a deamon for serving PHP cgi. Install php-fpm together with nginx.
-
-By default php listens on a network socket. If you want it to listen to a
-Unix socket instead, change the pool configuration (`pool.d/www.conf`) as
-follows:
-
- ; Comment out the tcp listener and add the unix socket
- ;listen = 127.0.0.1:9000
- listen = /var/run/php5-fpm.sock
-
- ; Ensure that the daemon runs as the correct user
- listen.owner = www-data
- listen.group = www-data
- listen.mode = 0666
-
-Tell nginx that php files are special and to fastcgi_pass to the php-fpm
-unix socket by adding the location definition to the default configuration.
-
-``` nginx
-root /srv/nominatim/build/website;
-index search.php;
-location / {
- try_files $uri $uri/ @php;
-}
-
-location @php {
- fastcgi_param SCRIPT_FILENAME "$document_root$uri.php";
- fastcgi_param PATH_TRANSLATED "$document_root$uri.php";
- fastcgi_param QUERY_STRING $args;
- fastcgi_pass unix:/var/run/php/php7.3-fpm.sock;
- fastcgi_index index.php;
- include fastcgi_params;
-}
-
-location ~ [^/]\.php(/|$) {
- fastcgi_split_path_info ^(.+?\.php)(/.*)$;
- if (!-f $document_root$fastcgi_script_name) {
- return 404;
- }
- fastcgi_pass unix:/var/run/php7.3-fpm.sock;
- fastcgi_index search.php;
- include fastcgi.conf;
-}
+```
+wget -O Nominatim/data/country_osm_grid.sql.gz https://www.nominatim.org/data/country_grid.sql.gz
```
-Restart the nginx and php5-fpm services and the website should now be available
-at `http://localhost/`.
+### Building Nominatim
+The code must be built in a separate directory. Create the directory and
+change into it.
+
+```
+mkdir build
+cd build
+```
+
+Nominatim uses cmake and make for building. Assuming that you have created the
+build at the same level as the Nominatim source directory run:
+
+```
+cmake ../Nominatim
+make
+```
Now continue with [importing the database](Import.md).
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 4b097c8c..2e74b24a 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -18,6 +18,7 @@ pages:
- 'Basic Installation': 'admin/Installation.md'
- 'Importing' : 'admin/Import.md'
- 'Updating' : 'admin/Update.md'
+ - 'Deploying' : 'admin/Deployment.md'
- 'Nominatim UI' : 'admin/Setup-Nominatim-UI.md'
- 'Advanced Installations' : 'admin/Advanced-Installations.md'
- 'Migration from older Versions' : 'admin/Migration.md'