Photon Docker Image

The image supports two ways to build the search index via the IMPORT_MODE environment variable:

1. db (default): Downloads a prebuilt index (.tar.bz2) for a single region. This is the stable mode and supports scheduled updates using UPDATE_STRATEGY and UPDATE_INTERVAL.
2. jsonl (experimental): Builds the index inside the container from compressed OpenStreetMap JSONL dumps. This mode allows combining multiple regions and fine-tuning the import.

Note: jsonl mode is experimental, does not support scheduled updates, and requires FORCE_UPDATE=TRUE or a volume recreation to rebuild. It also does not support FILE_URL or MD5_URL.

# Example using experimental JSONL mode
services:
    photon:
        image: rtuszik/photon-docker:latest
        environment:
            - IMPORT_MODE=jsonl
            - REGION=germany,austria,switzerland-liechtenstein
            - LANGUAGES=en,de

To use the experimental jsonl mode, set IMPORT_MODE=jsonl. You can specify one or more regions in the REGION variable (comma-separated). When multiple regions are requested, the container downloads the smallest dump covering all requested areas (e.g., a continent or planet) and then filters it.

Available configuration options for jsonl mode:

• REGION: Comma-separated list of regions.
• LANGUAGES: List of languages (e.g., en,de).
• EXTRA_TAGS: (Optional) Additional OSM tags to include (e.g., surface,smoothness).
• IMPORT_GEOMETRIES: (Optional) Set to true to include full geometries.
• REVERSE_ONLY: Set to TRUE to build a reverse-geocoding-only index. This results in a smaller index and faster import, but disables forward search endpoints (/api, /structured) and /metrics, serving only the /reverse endpoint.

services:
    photon:
        image: rtuszik/photon-docker:latest
        environment:
            - IMPORT_MODE=jsonl
            - REGION=germany,austria,switzerland-liechtenstein
            - LANGUAGES=en,de
            # - EXTRA_TAGS=surface,smoothness
            # - IMPORT_GEOMETRIES=true
        volumes:
            - photon_data:/photon/data
        restart: unless-stopped
        ports:
            - "2322:2322"
volumes:
    photon_data:

When the container starts, the entrypoint follows a specific logic flow to ensure the index is ready:

1. Configuration Validation: The container logs all active configuration variables and validates them using validate_config().
2. Index Reconciliation: The system calls index.reconcile() to align the local state with requirements.
3. Forced Update Path: If FORCE_UPDATE is enabled, the container immediately attempts a forced update or JSONL import, bypassing existing index checks.
4. Initial Setup Path:
   • If no index is present and INITIAL_DOWNLOAD is enabled, it performs an initial download (always using the SEQUENTIAL strategy).
   • If no index is present but INITIAL_DOWNLOAD is disabled, the container logs a warning and stops.
5. Existing Index Path:
   • If an index exists and IMPORT_MODE is jsonl, it skips automatic rebuilds.
   • If an index exists and MIN_INDEX_DATE is set, it checks the index age via check_index_age(). If the index is too old, it performs a SEQUENTIAL update.

Note on Strategies: While UPDATE_STRATEGY can be set to PARALLEL, the very first download of an index is always performed using the SEQUENTIAL strategy to ensure stability.

The photon-docker application is configured primarily through environment variables. These variables control data import modes, update strategies, geographic regions, and networking parameters.

Boolean values are parsed from strings like true, 1, or t (case-insensitive). For list-based configurations (like LANGUAGES or EXTRA_TAGS), use a comma-separated string.

Key Configuration Groups

Data Import & Updates

• IMPORT_MODE: Mode for importing data (default: db).
• UPDATE_STRATEGY: Strategy for updates (default: SEQUENTIAL). Note: Setting FILE_URL automatically sets this to DISABLED.
• UPDATE_INTERVAL: Frequency of updates using suffixes: d (days), h (hours), or m (minutes). Default is 30d.
• FORCE_UPDATE: Force an update (default: False).
• INITIAL_DOWNLOAD: Whether to perform an initial download (default: True).
• IMPORT_GEOMETRIES: Whether to import geometries (default: False).
• REVERSE_ONLY: Whether to only process reverse geocoding (default: False).

Geographic & Language Scoping

• REGION: Comma-separated list of regions (continents, countries, or planets) to process.
• LANGUAGES: Comma-separated list of languages to include.
• EXTRA_TAGS: Comma-separated list of additional tags to apply.

Networking & API

• BASE_URL: The base URL for the service (default: https://r2.koalasec.org/public).
• PHOTON_LISTEN_IP: The IP address the Photon service listens on (default: 0.0.0.0).
• PHOTON_PARAMS: Additional parameters passed to Photon.
• JAVA_PARAMS: Additional parameters passed to the Java runtime.
• APPRISE_URLS: URLs for Apprise notifications (e.g., pover://user@token).

Reliability & Logging

• DOWNLOAD_MAX_RETRIES: Max retries for downloads (default: 3).
• CHECKSUM_MAX_RETRIES: Max retries for checksum verification (default: 3).
• SKIP_MD5_CHECK: Skip MD5 verification (default: False).
• LOG_LEVEL: Logging verbosity (e.g., INFO, DEBUG).
• ENABLE_METRICS: Enable metrics collection (default: False).