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.
 135 Simply point the configuration variable `NOMINATIM_DATABASE_DSN` to the
 136 server and follow the standard import documentation.
 137
 138 The import will be faster, if the import is run directly from the database
 139 machine. You can easily switch to a different machine for the query frontend
 140 after the import.
 141
 142 ## Moving the database to another machine
 143
 144 For some configurations it may be useful to run the import on one machine, then
 145 move the database to another machine and run the Nominatim service from there.
 146 For example, you might want to use a large machine to be able to run the import
 147 quickly but only want a smaller machine for production because there is not so
 148 much load. Or you might want to do the import once and then replicate the
 149 database to many machines.
 150
 151 The important thing to keep in mind when transferring the Nominatim installation
 152 is that you need to transfer the database _and the project directory_. Both
 153 parts are essential for your installation.
 154
 155 The Nominatim database can be transferred using the `pg_dump`/`pg_restore` tool.
 156 Make sure to use the same version of PostgreSQL and PostGIS on source and
 157 target machine.
 158
 159 !!! note
 160     Before creating a dump of your Nominatim database, consider running
 161     `nominatim freeze` first. Your database looses the ability to receive further
 162     data updates but the resulting database is only about a third of the size
 163     of a full database.
 164
 165 Next install nominatim-api on the target machine by following the standard
 166 installation instructions. Again, make sure to use the same version as the
 167 source machine.
 168
 169 Create a project directory on your destination machine and set up the `.env`
 170 file to match the configuration on the source machine. That's all.