]> git.openstreetmap.org Git - nominatim.git/blob - docs/admin/Advanced-Installations.md
Merge remote-tracking branch 'upstream/master'
[nominatim.git] / 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.