docs/admin/Installation.md

   1 # Basic Installation
   2
   3 This page contains generic installation instructions for Nominatim and its
   4 prerequisites. There are also step-by-step instructions available for
   5 the following operating systems:
   6
   7   * [Ubuntu 18.04](../appendix/Install-on-Ubuntu-18.md)
   8   * [Ubuntu 16.04](../appendix/Install-on-Ubuntu-16.md)
   9   * [CentOS 7.2](../appendix/Install-on-Centos-7.md)
  10
  11 These OS-specific instructions can also be found in executable form
  12 in the `vagrant/` directory.
  13
  14 Users have created instructions for other frameworks. We haven't tested those
  15 and can't offer support.
  16
  17   * [Docker](https://github.com/mediagis/nominatim-docker)
  18   * [Docker on Kubernetes](https://github.com/peter-evans/nominatim-k8s)
  19   * [Ansible](https://github.com/synthesio/infra-ansible-nominatim)
  20
  21 ## Prerequisites
  22
  23 ### Software
  24
  25 For compiling:
  26
  27   * [cmake](https://cmake.org/)
  28   * [libxml2](http://xmlsoft.org/)
  29   * a recent C++ compiler
  30
  31 Nominatim comes with its own version of osm2pgsql. See the
  32 [osm2pgsql README](https://github.com/openstreetmap/osm2pgsql/blob/master/README.md#building)
  33 for additional dependencies required for compiling osm2pgsql.
  34
  35 For running tests:
  36
  37   * [behave](http://pythonhosted.org/behave/)
  38   * [Psycopg2](https://initd.org/psycopg)
  39   * [nose](https://nose.readthedocs.io)
  40   * [phpunit](https://phpunit.de)
  41
  42 For running Nominatim:
  43
  44   * [PostgreSQL](https://www.postgresql.org) (9.3 or later)
  45   * [PostGIS](https://postgis.org) (2.2 or later)
  46   * [PHP](https://php.net) (7.0 or later)
  47   * PHP-pgsql
  48   * PHP-intl (bundled with PHP)
  49   * a webserver (apache or nginx are recommended)
  50
  51 For running continuous updates:
  52
  53   * [pyosmium](https://osmcode.org/pyosmium/) (with Python 3)
  54
  55 ### Hardware
  56
  57 A minimum of 2GB of RAM is required or installation will fail. For a full
  58 planet import 64GB of RAM or more are strongly recommended. Do not report
  59 out of memory problems if you have less than 64GB RAM.
  60
  61 For a full planet install you will need at least 800GB of hard disk space
  62 (take into account that the OSM database is growing fast). SSD disks
  63 will help considerably to speed up import and queries.
  64
  65 Even on a well configured machine the import of a full planet takes
  66 at least 2 days. Without SSDs 7-8 days are more realistic.
  67
  68 ## Setup of the server
  69
  70 ### PostgreSQL tuning
  71
  72 You might want to tune your PostgreSQL installation so that the later steps
  73 make best use of your hardware. You should tune the following parameters in
  74 your `postgresql.conf` file.
  75
  76     shared_buffers = 2GB
  77     maintenance_work_mem = (10GB)
  78     autovacuum_work_mem = 2GB
  79     work_mem = (50MB)
  80     effective_cache_size = (24GB)
  81     synchronous_commit = off
  82     checkpoint_segments = 100 # only for postgresql <= 9.4
  83     max_wal_size = 1GB # postgresql > 9.4
  84     checkpoint_timeout = 10min
  85     checkpoint_completion_target = 0.9
  86
  87 The numbers in brackets behind some parameters seem to work fine for
  88 64GB RAM machine. Adjust to your setup. A higher number for `max_wal_size`
  89 means that PostgreSQL needs to run checkpoints less often but it does require
  90 the additional space on your disk.
  91
  92 For the initial import, you should also set:
  93
  94     fsync = off
  95     full_page_writes = off
  96
  97 Don't forget to reenable them after the initial import or you risk database
  98 corruption. Autovacuum must not be switched off because it ensures that the
  99 tables are frequently analysed.
 100
 101 ### Webserver setup
 102
 103 The `website/` directory in the build directory contains the configured
 104 website. Include the directory into your webbrowser to serve php files
 105 from there.
 106
 107 #### Configure for use with Apache
 108
 109 Make sure your Apache configuration contains the required permissions for the
 110 directory and create an alias:
 111
 112     <Directory "/srv/nominatim/build/website">
 113       Options FollowSymLinks MultiViews
 114       AddType text/html   .php
 115       DirectoryIndex search.php
 116       Require all granted
 117     </Directory>
 118     Alias /nominatim /srv/nominatim/build/website
 119
 120 `/srv/nominatim/build` should be replaced with the location of your
 121 build directory.
 122
 123 After making changes in the apache config you need to restart apache.
 124 The website should now be available on http://localhost/nominatim.
 125
 126 #### Configure for use with Nginx
 127
 128 Use php-fpm as a deamon for serving PHP cgi. Install php-fpm together with nginx.
 129
 130 By default php listens on a network socket. If you want it to listen to a
 131 Unix socket instead, change the pool configuration (`pool.d/www.conf`) as
 132 follows:
 133
 134     ; Comment out the tcp listener and add the unix socket
 135     ;listen = 127.0.0.1:9000
 136     listen = /var/run/php5-fpm.sock
 137
 138     ; Ensure that the daemon runs as the correct user
 139     listen.owner = www-data
 140     listen.group = www-data
 141     listen.mode = 0666
 142
 143 Tell nginx that php files are special and to fastcgi_pass to the php-fpm
 144 unix socket by adding the location definition to the default configuration.
 145
 146     root /srv/nominatim/build/website;
 147     index search.php index.html;
 148     location ~ [^/]\.php(/|$) {
 149         fastcgi_split_path_info ^(.+?\.php)(/.*)$;
 150         if (!-f $document_root$fastcgi_script_name) {
 151             return 404;
 152         }
 153         fastcgi_pass unix:/var/run/php5-fpm.sock;
 154         fastcgi_index search.php;
 155         include fastcgi.conf;
 156     }
 157
 158 Restart the nginx and php5-fpm services and the website should now be available
 159 at `http://localhost/`.
 160
 161
 162 Now continue with [importing the database](Import-and-Update.md).