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