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   * [expat](https://libexpat.github.io/)
  29   * [proj](https://proj.org/)
  30   * [bzip2](http://www.bzip.org/)
  31   * [zlib](https://www.zlib.net/)
  32   * [Boost libraries](https://www.boost.org/), including system and filesystem
  33   * PostgreSQL client libraries
  34   * a recent C++ compiler (gcc 5+ or Clang 3.8+)
  35
  36 For running Nominatim:
  37
  38   * [PostgreSQL](https://www.postgresql.org) (9.3 or later)
  39   * [PostGIS](https://postgis.org) (2.2 or later)
  40   * [Python 3](https://www.python.org/)
  41   * [Psycopg2](https://initd.org/psycopg)
  42   * [PHP](https://php.net) (7.0 or later)
  43   * PHP-pgsql
  44   * PHP-intl (bundled with PHP)
  45   * a webserver (apache or nginx are recommended)
  46
  47 For running continuous updates:
  48
  49   * [pyosmium](https://osmcode.org/pyosmium/) (with Python 3)
  50
  51 For running tests:
  52
  53   * [behave](http://pythonhosted.org/behave/)
  54   * [nose](https://nose.readthedocs.io)
  55   * [phpunit](https://phpunit.de)
  56
  57 ### Hardware
  58
  59 A minimum of 2GB of RAM is required or installation will fail. For a full
  60 planet import 64GB of RAM or more are strongly recommended. Do not report
  61 out of memory problems if you have less than 64GB RAM.
  62
  63 For a full planet install you will need at least 800GB of hard disk space
  64 (take into account that the OSM database is growing fast). SSD disks
  65 will help considerably to speed up import and queries.
  66
  67 Even on a well configured machine the import of a full planet takes
  68 at least 2 days. Without SSDs 7-8 days are more realistic.
  69
  70 ## Setup of the server
  71
  72 ### PostgreSQL tuning
  73
  74 You might want to tune your PostgreSQL installation so that the later steps
  75 make best use of your hardware. You should tune the following parameters in
  76 your `postgresql.conf` file.
  77
  78     shared_buffers = 2GB
  79     maintenance_work_mem = (10GB)
  80     autovacuum_work_mem = 2GB
  81     work_mem = (50MB)
  82     effective_cache_size = (24GB)
  83     synchronous_commit = off
  84     checkpoint_segments = 100 # only for postgresql <= 9.4
  85     max_wal_size = 1GB # postgresql > 9.4
  86     checkpoint_timeout = 10min
  87     checkpoint_completion_target = 0.9
  88
  89 The numbers in brackets behind some parameters seem to work fine for
  90 64GB RAM machine. Adjust to your setup. A higher number for `max_wal_size`
  91 means that PostgreSQL needs to run checkpoints less often but it does require
  92 the additional space on your disk.
  93
  94 Autovacuum must not be switched off because it ensures that the
  95 tables are frequently analysed. If your machine has very little memory,
  96 you might consider setting:
  97
  98     autovacuum_max_workers = 1
  99
 100 and even reduce `autovacuum_work_mem` further. This will reduce the amount
 101 of memory that autovacuum takes away from the import process.
 102
 103 For the initial import, you should also set:
 104
 105     fsync = off
 106     full_page_writes = off
 107
 108 Don't forget to reenable them after the initial import or you risk database
 109 corruption.
 110
 111
 112 ### Webserver setup
 113
 114 The `website/` directory in the build directory contains the configured
 115 website. Include the directory into your webbrowser to serve php files
 116 from there.
 117
 118 #### Configure for use with Apache
 119
 120 Make sure your Apache configuration contains the required permissions for the
 121 directory and create an alias:
 122
 123     <Directory "/srv/nominatim/build/website">
 124       Options FollowSymLinks MultiViews
 125       AddType text/html   .php
 126       DirectoryIndex search.php
 127       Require all granted
 128     </Directory>
 129     Alias /nominatim /srv/nominatim/build/website
 130
 131 `/srv/nominatim/build` should be replaced with the location of your
 132 build directory.
 133
 134 After making changes in the apache config you need to restart apache.
 135 The website should now be available on http://localhost/nominatim.
 136
 137 #### Configure for use with Nginx
 138
 139 Use php-fpm as a deamon for serving PHP cgi. Install php-fpm together with nginx.
 140
 141 By default php listens on a network socket. If you want it to listen to a
 142 Unix socket instead, change the pool configuration (`pool.d/www.conf`) as
 143 follows:
 144
 145     ; Comment out the tcp listener and add the unix socket
 146     ;listen = 127.0.0.1:9000
 147     listen = /var/run/php5-fpm.sock
 148
 149     ; Ensure that the daemon runs as the correct user
 150     listen.owner = www-data
 151     listen.group = www-data
 152     listen.mode = 0666
 153
 154 Tell nginx that php files are special and to fastcgi_pass to the php-fpm
 155 unix socket by adding the location definition to the default configuration.
 156
 157     root /srv/nominatim/build/website;
 158     index search.php index.html;
 159     location ~ [^/]\.php(/|$) {
 160         fastcgi_split_path_info ^(.+?\.php)(/.*)$;
 161         if (!-f $document_root$fastcgi_script_name) {
 162             return 404;
 163         }
 164         fastcgi_pass unix:/var/run/php5-fpm.sock;
 165         fastcgi_index search.php;
 166         include fastcgi.conf;
 167     }
 168
 169 Restart the nginx and php5-fpm services and the website should now be available
 170 at `http://localhost/`.
 171
 172
 173 Now continue with [importing the database](Import-and-Update.md).