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