From: Sarah Hoffmann Date: Tue, 15 Sep 2020 21:51:25 +0000 (+0200) Subject: docs: move webserver installation into separate chapter X-Git-Tag: v3.6.0~77^2~7 X-Git-Url: https://git.openstreetmap.org./nominatim.git/commitdiff_plain/cf4f62c82c96d7718a57d6852654210973a0ff57?ds=sidebyside docs: move webserver installation into separate chapter --- 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 + +### Downloading the latest release + +You can download the [latest release from nominatim.org](https://nominatim.org/downloads/). +The release contains all necessary files. Just unpack it. -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 development version -#### Configure for use with Apache +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 +``` -Make sure your Apache configuration contains the required permissions for the -directory and create an alias: +The development version does not include the country grid. Download it separately: -``` apache - - Options FollowSymLinks MultiViews - AddType text/html .php - DirectoryIndex search.php - Require all granted - -Alias /nominatim /srv/nominatim/build/website ``` +wget -O Nominatim/data/country_osm_grid.sql.gz https://www.nominatim.org/data/country_grid.sql.gz +``` + +### Building Nominatim + +The code must be built in a separate directory. Create the directory and +change into it. -`/srv/nominatim/build` should be replaced with the location of your -build directory. - -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; -} +``` +mkdir build +cd build ``` -Restart the nginx and php5-fpm services and the website should now be available -at `http://localhost/`. +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'