control cache warmup with environment variable

This commit introduces a new environment variable, WARMUP_ON_STARTUP, to control whether the Nominatim caches are warmed up when the container starts.

Previously, the cache warming process ran unconditionally on every startup. This could be time-consuming and unnecessary in environments where a quick start is prioritized over a pre-warmed cache.

Author: philipkozeny

.github/workflows/ci.yml

@@ -232,6 +232,30 @@ jobs:
               # Verify that the exit code is zero
               CONTAINER_EXIT_CODE=$(docker inspect nominatim --format='{{.State.ExitCode}}')
               test "$CONTAINER_EXIT_CODE" -eq 0
+
+          - name: WARMUP_ON_STARTUP=true
+            commands: |-
+              docker run -i --rm \
+                -e PBF_URL=http://download.geofabrik.de/europe/monaco-latest.osm.pbf \
+                -e WARMUP_ON_STARTUP=true \
+                -p 8012:8080 \
+                --name nominatim \
+                nominatim &
+
+              ./assert-non-empty-json "http://localhost:8012/search.php?q=avenue%20pasteur"
+              docker logs nominatim | grep "Warming finished"
+
+          - name: WARMUP_ON_STARTUP=false
+            commands: |-
+              docker run -i --rm \
+                -e PBF_URL=http://download.geofabrik.de/europe/monaco-latest.osm.pbf \
+                -e WARMUP_ON_STARTUP=false \
+                -p 8013:8080 \
+                --name nominatim \
+                nominatim &
+
+              ./assert-non-empty-json "http://localhost:8013/search.php?q=avenue%20pasteur"
+              docker logs nominatim | grep "Skipping cache warmup"
     
     steps:
       - name: Download artifact

5.0/Dockerfile

@@ -96,6 +96,7 @@ COPY --from=build / /
 
 # Please override this
 ENV NOMINATIM_PASSWORD=qaIACxO6wMR3
+ENV WARMUP_ON_STARTUP=false
 
 ENV PROJECT_DIR=/nominatim
 

5.0/README.md

@@ -63,6 +63,7 @@ Other places at Geofabrik follow the pattern `https://download.geofabrik.de/$CON
 - `IMPORT_TIGER_ADDRESSES`: Whether to download and import the Tiger address data (`true`) or path to a preprocessed Tiger address set in the container. (default: `false`)
 - `THREADS`: How many threads should be used to import (default: number of processing units available to the current process via `nproc`)
 - `NOMINATIM_PASSWORD`: The password to connect to the database with (default: `qaIACxO6wMR3`)
+- `WARMUP_ON_STARTUP`: Whether to warm up the database caches on container startup by loading tables and indices into RAM. This can improve initial query performance, especially on systems with slow disks and sufficient RAM. However, it will increase the container's startup time. Set to `true` to enable. (default: `false`)
 
 The following run parameters are available for configuration:
 

5.0/start.sh

@@ -67,18 +67,22 @@ fi
 tail -Fv /var/log/postgresql/postgresql-16-main.log &
 tailpid=${!}
 
-export NOMINATIM_QUERY_TIMEOUT=600
-export NOMINATIM_REQUEST_TIMEOUT=3600
-if [ "$REVERSE_ONLY" = "true" ]; then
-  echo "Warm database caches for reverse queries"
-  sudo -H -E -u nominatim nominatim admin --warm --reverse > /dev/null
+if [ "$WARMUP_ON_STARTUP" = "true" ]; then
+  export NOMINATIM_QUERY_TIMEOUT=600
+  export NOMINATIM_REQUEST_TIMEOUT=3600
+  if [ "$REVERSE_ONLY" = "true" ]; then
+    echo "Warm database caches for reverse queries"
+    sudo -H -E -u nominatim nominatim admin --warm --reverse > /dev/null
+  else
+    echo "Warm database caches for search and reverse queries"
+    sudo -H -E -u nominatim nominatim admin --warm > /dev/null
+  fi
+  export NOMINATIM_QUERY_TIMEOUT=10
+  export NOMINATIM_REQUEST_TIMEOUT=60
+  echo "Warming finished"
 else
-  echo "Warm database caches for search and reverse queries"
-  sudo -H -E -u nominatim nominatim admin --warm > /dev/null
+  echo "Skipping cache warmup"
 fi
-export NOMINATIM_QUERY_TIMEOUT=10
-export NOMINATIM_REQUEST_TIMEOUT=60
-echo "Warming finished"
 
 echo "--> Nominatim is ready to accept requests"
 

5.1/Dockerfile

@@ -90,6 +90,7 @@ COPY --from=build / /
 
 # Please override this
 ENV NOMINATIM_PASSWORD=qaIACxO6wMR3
+ENV WARMUP_ON_STARTUP=false
 
 ENV PROJECT_DIR=/nominatim
 

5.1/README.md

@@ -64,6 +64,7 @@ Other places at Geofabrik follow the pattern `https://download.geofabrik.de/$CON
 - `THREADS`: How many threads should be used to import (default: number of processing units available to the current process via `nproc`)
 - `GUNICORN_WORKERS`: Specifies how many Gunicorn worker processes should handle API requests. If not explicitly set, it defaults to the number of available CPU cores `(nproc)`. Increase this value to improve concurrent request handling capacity, but ensure it aligns with your server's CPU resources.
 - `NOMINATIM_PASSWORD`: The password to connect to the database with (default: `qaIACxO6wMR3`)
+- `WARMUP_ON_STARTUP`: Whether to warm up the database caches on container startup by loading tables and indices into RAM. This can improve initial query performance, especially on systems with slow disks and sufficient RAM. However, it will increase the container's startup time. Set to `true` to enable. (default: `false`)
 
 The following run parameters are available for configuration:
 

5.1/start.sh

@@ -67,18 +67,22 @@ fi
 tail -Fv /var/log/postgresql/postgresql-16-main.log &
 tailpid=${!}
 
-export NOMINATIM_QUERY_TIMEOUT=600
-export NOMINATIM_REQUEST_TIMEOUT=3600
-if [ "$REVERSE_ONLY" = "true" ]; then
-  echo "Warm database caches for reverse queries"
-  sudo -H -E -u nominatim nominatim admin --warm --reverse > /dev/null
+if [ "$WARMUP_ON_STARTUP" = "true" ]; then
+  export NOMINATIM_QUERY_TIMEOUT=600
+  export NOMINATIM_REQUEST_TIMEOUT=3600
+  if [ "$REVERSE_ONLY" = "true" ]; then
+    echo "Warm database caches for reverse queries"
+    sudo -H -E -u nominatim nominatim admin --warm --reverse > /dev/null
+  else
+    echo "Warm database caches for search and reverse queries"
+    sudo -H -E -u nominatim nominatim admin --warm > /dev/null
+  fi
+  export NOMINATIM_QUERY_TIMEOUT=10
+  export NOMINATIM_REQUEST_TIMEOUT=60
+  echo "Warming finished"
 else
-  echo "Warm database caches for search and reverse queries"
-  sudo -H -E -u nominatim nominatim admin --warm > /dev/null
+  echo "Skipping cache warmup"
 fi
-export NOMINATIM_QUERY_TIMEOUT=10
-export NOMINATIM_REQUEST_TIMEOUT=60
-echo "Warming finished"
 
 # Set default number of workers if not specified
 if [ -z "$GUNICORN_WORKERS" ]; then