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