Installation¶
Docker¶
If you already run immich with Docker Compose, the simplest setup is to add one service to that existing compose file.
Database backup strongly recommended
This service updates immich metadata in the database.
Before first use, and especially before using any bulk-clear action from the Data page, create a proper immich database backup.
Official guide: Backup and Restore | Immich
Choose your Compose setup¶
Add the service and volume declarations below to your existing Immich Compose file. Reuse its .env file and default network. Keep /config and /data persisted separately.
# docker-compose.yml
# Add this service to your existing Immich docker-compose.yml.
services:
immich-reversegeo:
image: ghcr.io/immich-reversegeo/immich-reversegeo:latest
container_name: immich-reversegeo
pull_policy: always
ports:
- "8080:8080" # change the left side if 8080 is already in use; do NOT expose publicly
volumes:
- reversegeo-config:/config # settings (no database secrets in settings.json)
- reversegeo-data:/data # Overture caches, skipped.db, runtime data
env_file:
- .env # reuse Immich's own .env (DB_USERNAME, DB_PASSWORD, etc.)
environment:
- ASPNETCORE_URLS=http://+:8080
# Optional photo previews and original-photo links:
# - IMMICH_URL=http://immich-server:2283
# - IMMICH_WEB_URL=https://photos.example.com
# - IMMICH_API_KEY=${REVERSEGEO_IMMICH_API_KEY}
mem_limit: 2g
restart: unless-stopped
volumes:
reversegeo-config:
reversegeo-data:
Start only Immich ReverseGeo:
docker compose up -d immich-reversegeo
Save the same service snippet in a separate directory and provide an .env file with your Immich database connection values. Join the existing Immich network by adding this section to that Compose file:
networks:
default:
external: true
name: immich_default
Replace immich_default with your actual Immich network name. The database hostname must be reachable on that network. You can inspect available networks with docker network ls.
docker compose up -d immich-reversegeo
Reference file: docker-compose.yml.
Both setups need about 2 GB of memory, as set by mem_limit in the service snippet.
Why the memory limit is there
The bundled country boundary data is held in memory while processing runs and uses several hundred
megabytes. mem_limit sets a total container memory budget that the .NET runtime can take
into account. Large country caches and high parallelism can increase peak memory use.
Do not lower it much below 2g. A limit under the working set makes the container fail
immediately instead of running. Raising it is fine.
Both setups need the database connection values from Immich:
DB_HOSTNAME=database
DB_PORT=5432
DB_USERNAME=postgres
DB_PASSWORD=...
DB_DATABASE_NAME=immich
Use DB_HOSTNAME from Immich's .env file, including when connecting to an external database. A nonblank DB_HOST takes precedence over DB_HOSTNAME for existing installations. If DB_HOST is empty or contains only spaces, the app uses DB_HOSTNAME. If neither has a nonblank value, the host defaults to database.
The example publishes the UI on host port 8080. Change the left side of the port mapping if it is already in use. Do not expose the UI publicly; see the private-access options below.
Image versions¶
latest normally follows GitHub's designated latest stable release after its image is successfully published. Maintainers can explicitly promote another validated build using the manual publishing option. Use a published version tag to control upgrades, for example ghcr.io/immich-reversegeo/immich-reversegeo:1.2.3. This is an example; choose an available version from GitHub Releases.
- Releases tagged
v1.2.3publish both1.2.3andv1.2.3image tags. - Other stable releases retain their version tags without changing
latest. Rerunning an older release does not automatically movelatestbackwards. - Prereleases publish their full version tags, such as
1.2.3-rc.1, without updatinglatest. edgefollows development builds frommasterafter the build, tests, and Docker build checks pass.sha-...tags identify builds by commit.
After changing the image version in your Compose file, run docker compose pull immich-reversegeo and docker compose up -d immich-reversegeo. Keep your existing /config and /data volumes.
VPS and firewall notes¶
Do not expose the web UI publicly. Docker-published ports can bypass host firewall rules such as UFW, so do not rely on the host firewall alone to hide a broadly published 8080:8080 mapping on an internet-facing server.
If you run Immich ReverseGeo on a VPS and only need local or SSH-forwarded access, bind the published port to localhost:
ports:
- "127.0.0.1:8080:8080"
# - "[::1]:8080:8080"
Then use a private path such as SSH local port forwarding, a VPN, or a trusted reverse proxy with authentication:
ssh -N -L 8080:localhost:8080 user@host
Then open:
http://localhost:8080
Runtime notes¶
- Built-in data covers country matching and airport matching.
- More detailed country data is downloaded only when needed.
- The app needs internet access the first time it downloads data for a new country.
- Large countries can use hundreds of megabytes each under
/data.
After install¶
- Use Configuration for database and processing settings.
- Use Using the App for manual runs, coordinate testing, and reset tools.