What is photon-docker?

This project provides a Docker image for running the Photon geocoder on your own infrastructure. Photon is an open-source geocoding engine that uses OpenStreetMap data to offer search-as-you-type and reverse geocoding. The container supports two ways to build its index: downloading a ready-made index for a single region, or building one from raw OSM JSONL dumps (the latter is experimental and can combine multiple regions). Automatic index updates are available with parallel or sequential strategies. You can choose from planet-wide data, continents, or specific countries. Prometheus metrics can be enabled, and the image defaults to community mirrors to ease load on the official GraphHopper servers. The service listens on port 2322 and works with tools like Dawarich for location history. Be aware that the planet index exceeds 60 GB and the first import can take many hours.

Should you self-host photon-docker?

photon-docker scores 48/100 on selfhost.directory (how scoring works) and ranks #5 of 8 in Geospatial. It has 319 GitHub stars.

It shipped 11 stable releases in the past year. The latest, 2.5.0, came out on 25 October 2026. New versions land roughly every 4 weeks.

Setup is moderate: expect some configuration beyond a single command. An official Docker image is available. It is Apache-2.0-licensed and written mostly in Python.

Its closest alternative on selfhost.directory is QGIS (81/100, 14 728 stars). It scores higher overall, so compare the two before you pick. See photon-docker vs QGIS side by side.

Features

Automatic index updatesOnly in db mode
Community mirrors
Geocoding
Multiple import modes
Multiple region support16 regions have prebuilt DB indexes; many more available in jsonl mode
Prometheus Metrics
Reverse Geocoding

How to configure photon-docker

APPRISE_URLSOptional notification URLs for Apprise to send status updates (e.g., download completion, errors). Supports multiple services like Pushover, Slack, email, etc. Example: `pover://user@token,mailto://user:pass@gmail.com`
Optional notification URLs for Apprise to send status updates (e.g., download completion, errors). Supports multiple services like Pushover, Slack, email, etc. Example: `pover://user@token,mailto://user:pass@gmail.com`
BASE_URLhttps://r2.koalasec.org/publicCustom base URL for index data downloads. Should point to the parent directory of index files. The default has been changed to a community mirror to reduce load on the GraphHopper servers.
Custom base URL for index data downloads. Should point to the parent directory of index files. The default has been changed to a community mirror to reduce load on the GraphHopper servers.
CHECKSUM_MAX_RETRIES3Maximum number of download attempts when the MD5 checksum of the downloaded index does not match. A corrupted download is re-fetched up to this many times before the update fails. Ignored when `SKIP_MD5_CHECK` is enabled.
Maximum number of download attempts when the MD5 checksum of the downloaded index does not match. A corrupted download is re-fetched up to this many times before the update fails. Ignored when `SKIP_MD5_CHECK` is enabled.
DOWNLOAD_MAX_RETRIES3Maximum number of retries for failed downloads.
Maximum number of retries for failed downloads.
ENABLE_METRICSFALSEEnables Prometheus Metrics endpoint at /metrics
Enables Prometheus Metrics endpoint at /metrics
EXTRA_TAGSOnly used in `jsonl` mode. Additional OSM tags to import, passed to Photon's `-extra-tags`.
Only used in `jsonl` mode. Additional OSM tags to import, passed to Photon's `-extra-tags`.
FILE_URLSet a custom URL for the index file to be downloaded (e.g., "https://download1.graphhopper.com/public/experimental/photon-db-latest.tar.bz2"). This must be a tar.bz2 format. Setting this overrides `UPDATE_STRATEGY` to `DISABLED`, and `SKIP_MD5_CHECK` to true if `MD5_URL` is not set.
Set a custom URL for the index file to be downloaded (e.g., "https://download1.graphhopper.com/public/experimental/photon-db-latest.tar.bz2"). This must be a tar.bz2 format. Setting this overrides `UPDATE_STRATEGY` to `DISABLED`, and `SKIP_MD5_CHECK` to true if `MD5_URL` is not set.
FORCE_UPDATEFALSEForces an index update on container startup, regardless of `UPDATE_STRATEGY`.
Forces an index update on container startup, regardless of `UPDATE_STRATEGY`.
IMPORT_GEOMETRIESFALSEOnly used in `jsonl` mode. When `TRUE`, imports full geometries (`-full-geometries`) instead of centroids.
Only used in `jsonl` mode. When `TRUE`, imports full geometries (`-full-geometries`) instead of centroids.
IMPORT_MODEdbSelects how the index is built. `db` downloads a prebuilt index for a single region. `jsonl` (experimental) builds the index in-container from OpenStreetMap JSONL dumps and supports combining multiple regions. See Import Modes.
Selects how the index is built. `db` downloads a prebuilt index for a single region. `jsonl` (experimental) builds the index in-container from OpenStreetMap JSONL dumps and supports combining multiple regions. See Import Modes.
INITIAL_DOWNLOADTRUEControls whether the container performs the initial index download when the Photon data directory is empty. Useful for manual imports.
Controls whether the container performs the initial index download when the Photon data directory is empty. Useful for manual imports.
JAVA_PARAMSExtra parameters passed to the `java` command that runs Photon (e.g. heap settings like `-Xmx4g`).
Extra parameters passed to the `java` command that runs Photon (e.g. heap settings like `-Xmx4g`).
LANGUAGESOnly used in `jsonl` mode. Languages to import, passed to Photon's `-languages` (e.g. `en,de,fr`).
Only used in `jsonl` mode. Languages to import, passed to Photon's `-languages` (e.g. `en,de,fr`).
LOG_LEVELINFOControls logging verbosity.
Controls logging verbosity.
MD5_URLSet a custom URL for the md5 file to be downloaded (e.g., "https://download1.graphhopper.com/public/experimental/photon-db-latest.tar.bz2.md5").
Set a custom URL for the md5 file to be downloaded (e.g., "https://download1.graphhopper.com/public/experimental/photon-db-latest.tar.bz2.md5").
PGID9011The Group ID for the photon process. Set this to your host group's ID (`id -g`) to prevent permission errors when using bind mounts.
The Group ID for the photon process. Set this to your host group's ID (`id -g`) to prevent permission errors when using bind mounts.
PHOTON_LISTEN_IP0.0.0.0Populates `-listen-ip` parameter for photon
Populates `-listen-ip` parameter for photon
PHOTON_PARAMSSee `https://github.com/komoot/photon#running-photon.`
See `https://github.com/komoot/photon#running-photon.`
PUID9011The User ID for the photon process. Set this to your host user's ID (`id -u`) to prevent permission errors when using bind mounts.
The User ID for the photon process. Set this to your host user's ID (`id -u`) to prevent permission errors when using bind mounts.
REGIONplanetRegion for a specific dataset. Can be a continent (`europe`, `asia`), individual country/region (`germany`, `usa`, `japan`), country code (`de`, `us`, `jp`), or `planet` for worldwide data. In `db` mode exactly one region may be set, and it must be one with a prebuilt index. In `jsonl` mode you may pass multiple regions as a comma-separated list. See Available Regions section for details.
Region for a specific dataset. Can be a continent (`europe`, `asia`), individual country/region (`germany`, `usa`, `japan`), country code (`de`, `us`, `jp`), or `planet` for worldwide data. In `db` mode exactly one region may be set, and it must be one with a prebuilt index. In `jsonl` mode you may pass multiple regions as a comma-separated list. See Available Regions section for details.
REVERSE_ONLYFALSEOnly used in `jsonl` mode. When `TRUE`, builds a reverse-geocoding-only index (`-reverse-only`), saving roughly 60% of disk space and import time. The forward search endpoints (`/api`, `/structured`) and `/metrics` are disabled on the resulting index; only `/reverse` is served.
Only used in `jsonl` mode. When `TRUE`, builds a reverse-geocoding-only index (`-reverse-only`), saving roughly 60% of disk space and import time. The forward search endpoints (`/api`, `/structured`) and `/metrics` are disabled on the resulting index; only `/reverse` is served.
SKIP_MD5_CHECKFALSEOptionally skip MD5 verification of downloaded index files.
Optionally skip MD5 verification of downloaded index files.
SKIP_SPACE_CHECKFALSESkip disk space verification before downloading.
Skip disk space verification before downloading.
UPDATE_INTERVAL30dMinimum age of the local index before checking the mirror for a newer version. Once reached, the mirror is checked at most once per hour until a newer index is available. The age persists across container restarts. To reduce server load, set this to a long interval (e.g., `720h` for 30 days) or disable updates altogether if you do not need the latest data.
Minimum age of the local index before checking the mirror for a newer version. Once reached, the mirror is checked at most once per hour until a newer index is available. The age persists across container restarts. To reduce server load, set this to a long interval (e.g., `720h` for 30 days) or disable updates altogether if you do not need the latest data.
UPDATE_STRATEGYSEQUENTIALControls how index updates are handled. `PARALLEL` downloads the new index in the background then swaps with minimal downtime (requires 2x space). `SEQUENTIAL` stops Photon, deletes the existing index, downloads the new one, then restarts. `DISABLED` prevents automatic updates. Only applies in `db` mode.
Controls how index updates are handled. `PARALLEL` downloads the new index in the background then swaps with minimal downtime (requires 2x space). `SEQUENTIAL` stops Photon, deletes the existing index, downloads the new one, then restarts. `DISABLED` prevents automatic updates. Only applies in `db` mode.