add warning about experimental nature of ICU tokenizer

[nominatim.git] / docs / admin / Advanced-Installations.md

diff --git a/docs/admin/Advanced-Installations.md b/docs/admin/Advanced-Installations.md
index b22d9a6179e32410e568ae237e12bcc27b05b083..d5e6e889b2da1c92dd4fd3b4cfe1266b60a04894 100644 (file)
--- a/docs/admin/Advanced-Installations.md
+++ b/docs/admin/Advanced-Installations.md
@@ -47,14 +47,16 @@ The file `import_multiple_regions.sh` needs to be edited as per your requirement
     
         BASEURL="https://download.geofabrik.de"
         DOWNCOUNTRYPOSTFIX="-latest.osm.pbf"
- 
-!!! tip
-    If your database already exists and you want to add more countries, replace the setting up part
-    `${SETUPFILE} --osm-file ${UPDATEDIR}/tmp/combined.osm.pbf --all 2>&1`
-    with `${UPDATEFILE} --import-file ${UPDATEDIR}/tmp/combined.osm.pbf 2>&1`.
 
 ### Setting up multiple regions
 
+!!! tip
+    If your database already exists and you want to add more countries,
+    replace the setting up part
+    `${SETUPFILE} --osm-file ${UPDATEDIR}/tmp/combined.osm.pbf --all 2>&1`
+    with `${UPDATEFILE} --import-file ${UPDATEDIR}/tmp/combined.osm.pbf --index --index-instances N 2>&1`
+    where N is the numbers of CPUs in your system.
+
 Run the following command from your Nominatim directory after configuring the file.
 
     bash ./utils/import_multiple_regions.sh
@@ -63,7 +65,7 @@ Run the following command from your Nominatim directory after configuring the fi
         This file uses osmium-tool. It must be installed before executing the import script.
         Installation instructions can be found [here](https://osmcode.org/osmium-tool/manual.html#installation).
 
-## Updating multiple regions
+### Updating multiple regions
 
 To import multiple regions in your database, you need to configure and run ```utils/update_database.sh```.
 This uses the update directory set up while setting up the DB.   
@@ -101,9 +103,71 @@ Run the following command from your Nominatim directory after configuring the fi
 
     bash ./utils/update_database.sh
 
-This will get diffs from the replication server, import diffs and index the database. The default replication server in the script([Geofabric](https://download.geofabrik.de)) provides daily updates.
+This will get diffs from the replication server, import diffs and index the database. The default replication server in the script([Geofabrik](https://download.geofabrik.de)) provides daily updates.
+
+## Importing Nominatim to an external PostgreSQL database
+
+You can install Nominatim using a database that runs on a different server when
+you have physical access to the file system on the other server. Nominatim
+uses a custom normalization library that needs to be made accessible to the
+PostgreSQL server. This section explains how to set up the normalization
+library.
+
+### Option 1: Compiling the library on the database server
+
+The most sure way to get a working library is to compile it on the database
+server. From the prerequisites you need at least cmake, gcc and the
+PostgreSQL server package.
+
+Clone or unpack the Nominatim source code, enter the source directory and
+create and enter a build directory.
+
+```sh
+cd Nominatim
+mkdir build
+cd build
+```
+
+Now configure cmake to only build the PostgreSQL module and build it:
+
+```
+cmake -DBUILD_IMPORTER=off -DBUILD_API=off -DBUILD_TESTS=off -DBUILD_DOCS=off -DBUILD_OSM2PGSQL=off ..
+make
+```
+
+When done, you find the normalization library in `build/module/nominatim.so`.
+Copy it to a place where it is readable and executable by the PostgreSQL server
+process.
+
+### Option 2: Compiling the library on the import machine
 
-## Verification and further setup
+You can also compile the normalization library on the machine from where you
+run the import.
 
-Instructions for import verification and other details like importing Wikidata can be found in [import and update page](Import-and-Update.md)
+!!! important
+    You can only do this when the database server and the import machine have
+    the same architecture and run the same version of Linux. Otherwise there is
+    no guarantee that the compiled library is compatible with the PostgreSQL
+    server running on the database server.
+
+Make sure that the PostgreSQL server package is installed on the machine
+**with the same version as on the database server**. You do not need to install
+the PostgreSQL server itself.
+
+Download and compile Nominatim as per standard instructions. Once done, you find
+the normalization library in `build/module/nominatim.so`. Copy the file to
+the database server at a location where it is readable and executable by the
+PostgreSQL server process.
+
+### Running the import
+
+On the client side you now need to configure the import to point to the
+correct location of the library **on the database server**. Add the following
+line to your your `.env` file:
+
+```php
+NOMINATIM_DATABASE_MODULE_PATH="<directory on the database server where nominatim.so resides>"
+```
 
+Now change the `NOMINATIM_DATABASE_DSN` to point to your remote server and continue
+to follow the [standard instructions for importing](/admin/Import).