docs/admin/Advanced-Installations.md

   1 # Advanced installations
   2
   3 This page contains instructions for setting up multiple countries in
   4 your Nominatim database. It is assumed that you have already successfully
   5 installed the Nominatim software itself, if not return to the
   6 [installation page](Installation.md).
   7
   8 ## Importing multiple regions (without updates)
   9
  10 To import multiple regions in your database you can simply give multiple
  11 OSM files to the import command:
  12
  13 ```
  14 nominatim import --osm-file file1.pbf --osm-file file2.pbf
  15 ```
  16
  17 If you already have imported a file and want to add another one, you can
  18 use the add-data function to import the additional data as follows:
  19
  20 ```
  21 nominatim add-data --file <FILE>
  22 nominatim refresh --postcodes
  23 nominatim index -j <NUMBER OF THREADS>
  24 ```
  25
  26 Please note that adding additional data is always significantly slower than
  27 the original import.
  28
  29 ## Importing multiple regions (with updates)
  30
  31 If you want to import multiple regions _and_ be able to keep them up-to-date
  32 with updates, then you can use the scripts provided in the `utils` directory.
  33
  34 These scripts will set up an `update` directory in your project directory,
  35 which has the following structure:
  36
  37 ```bash
  38 update
  39     ├── europe
  40     │   ├── andorra
  41     │   │   └── sequence.state
  42     │   └── monaco
  43     │       └── sequence.state
  44     └── tmp
  45         └── europe
  46                 ├── andorra-latest.osm.pbf
  47                 └── monaco-latest.osm.pbf
  48
  49
  50 ```
  51
  52 The `sequence.state` files contain the sequence ID for each region. They will
  53 be used by pyosmium to get updates. The `tmp` folder is used for import dump and
  54 can be deleted once the import is complete.
  55
  56
  57 ### Setting up multiple regions
  58
  59 Create a project directory as described for the
  60 [simple import](Import.md#creating-the-project-directory). If necessary,
  61 you can also add an `.env` configuration with customized options. In particular,
  62 you need to make sure that `NOMINATIM_REPLICATION_UPDATE_INTERVAL` and
  63 `NOMINATIM_REPLICATION_RECHECK_INTERVAL` are set according to the update
  64 interval of the extract server you use.
  65
  66 Copy the scripts `utils/import_multiple_regions.sh` and `utils/update_database.sh`
  67 into the project directory.
  68
  69 Now customize both files as per your requirements
  70
  71 1. List of countries. e.g.
  72
  73         COUNTRIES="europe/monaco europe/andorra"
  74
  75 2. URL to the service providing the extracts and updates. eg:
  76
  77         BASEURL="https://download.geofabrik.de"
  78         DOWNCOUNTRYPOSTFIX="-latest.osm.pbf"
  79
  80 5. Followup in the update script can be set according to your installation.
  81    E.g. for Photon,
  82
  83         FOLLOWUP="curl http://localhost:2322/nominatim-update"
  84
  85     will handle the indexing.
  86
  87
  88 To start the initial import, change into the project directory and run
  89
  90 ```
  91     bash import_multiple_regions.sh
  92 ```
  93
  94 ### Updating the database
  95
  96 Change into the project directory and run the following command:
  97
  98     bash update_database.sh
  99
 100 This will get diffs from the replication server, import diffs and index
 101 the database. The default replication server in the
 102 script([Geofabrik](https://download.geofabrik.de)) provides daily updates.
 103
 104 ## Using an external PostgreSQL database
 105
 106 You can install Nominatim using a database that runs on a different server when
 107 you have physical access to the file system on the other server. Nominatim
 108 uses a custom normalization library that needs to be made accessible to the
 109 PostgreSQL server. This section explains how to set up the normalization
 110 library.
 111
 112 !!! note
 113     The external module is only needed when using the legacy tokenizer.
 114     If you have choosen the ICU tokenizer, then you can ignore this section
 115     and follow the standard import documentation.
 116
 117 ### Option 1: Compiling the library on the database server
 118
 119 The most sure way to get a working library is to compile it on the database
 120 server. From the prerequisites you need at least cmake, gcc and the
 121 PostgreSQL server package.
 122
 123 Clone or unpack the Nominatim source code, enter the source directory and
 124 create and enter a build directory.
 125
 126 ```sh
 127 cd Nominatim
 128 mkdir build
 129 cd build
 130 ```
 131
 132 Now configure cmake to only build the PostgreSQL module and build it:
 133
 134 ```
 135 cmake -DBUILD_IMPORTER=off -DBUILD_API=off -DBUILD_TESTS=off -DBUILD_DOCS=off -DBUILD_OSM2PGSQL=off ..
 136 make
 137 ```
 138
 139 When done, you find the normalization library in `build/module/nominatim.so`.
 140 Copy it to a place where it is readable and executable by the PostgreSQL server
 141 process.
 142
 143 ### Option 2: Compiling the library on the import machine
 144
 145 You can also compile the normalization library on the machine from where you
 146 run the import.
 147
 148 !!! important
 149     You can only do this when the database server and the import machine have
 150     the same architecture and run the same version of Linux. Otherwise there is
 151     no guarantee that the compiled library is compatible with the PostgreSQL
 152     server running on the database server.
 153
 154 Make sure that the PostgreSQL server package is installed on the machine
 155 **with the same version as on the database server**. You do not need to install
 156 the PostgreSQL server itself.
 157
 158 Download and compile Nominatim as per standard instructions. Once done, you find
 159 the normalization library in `build/module/nominatim.so`. Copy the file to
 160 the database server at a location where it is readable and executable by the
 161 PostgreSQL server process.
 162
 163 ### Running the import
 164
 165 On the client side you now need to configure the import to point to the
 166 correct location of the library **on the database server**. Add the following
 167 line to your your `.env` file:
 168
 169 ```php
 170 NOMINATIM_DATABASE_MODULE_PATH="<directory on the database server where nominatim.so resides>"
 171 ```
 172
 173 Now change the `NOMINATIM_DATABASE_DSN` to point to your remote server and continue
 174 to follow the [standard instructions for importing](Import.md).
 175
 176
 177 ## Moving the database to another machine
 178
 179 For some configurations it may be useful to run the import on one machine, then
 180 move the database to another machine and run the Nominatim service from there.
 181 For example, you might want to use a large machine to be able to run the import
 182 quickly but only want a smaller machine for production because there is not so
 183 much load. Or you might want to do the import once and then replicate the
 184 database to many machines.
 185
 186 The important thing to keep in mind when transferring the Nominatim installation
 187 is that you need to transfer the database _and the project directory_. Both
 188 parts are essential for your installation.
 189
 190 The Nominatim database can be transferred using the `pg_dump`/`pg_restore` tool.
 191 Make sure to use the same version of PostgreSQL and PostGIS on source and
 192 target machine.
 193
 194 !!! note
 195     Before creating a dump of your Nominatim database, consider running
 196     `nominatim freeze` first. Your database looses the ability to receive further
 197     data updates but the resulting database is only about a third of the size
 198     of a full database.
 199
 200 Next install Nominatim on the target machine by following the standard installation
 201 instructions. Again make sure to use the same version as the source machine.
 202
 203 You can now copy the project directory from the source machine to the new machine.
 204 If necessary, edit the `.env` file to point it to the restored database.
 205 Finally run
 206
 207     nominatim refresh --website
 208
 209 to make sure that the local installation of Nominatim will be used.
 210
 211 If you are using the legacy tokenizer you might also have to switch to the
 212 PostgreSQL module that was compiled on your target machine. If you get errors
 213 that PostgreSQL cannot find or access `nominatim.so` then copy the installed
 214 version into the `module` directory of your project directory. The installed
 215 copy can usually be found under `/usr/local/lib/nominatim/module/nominatim.so`.