Skip to content

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

Preferred setup

  • Add the service to your existing Immich docker-compose.yml.
  • Reuse the same .env file that already contains your Immich database settings.
  • Keep /config and /data persisted with Docker volumes.
  • No extra Docker network configuration is needed when the service lives in the same compose project as Immich.

Reference file: docker-compose.yml

Copy/paste snippet:

docker-compose.yml
# 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
    restart: unless-stopped

volumes:
  reversegeo-config:
  reversegeo-data:

This service expects:

  • the same database connection values Immich already uses
  • to run in the same compose project and Docker network as Immich
  • a persistent /config volume for settings
  • a persistent /data volume for downloaded Overture data and runtime state
  • a free host port for the web UI, with 8080 as the default example

Typical variables come from the shared .env file:

DB_HOST=database
DB_PORT=5432
DB_USERNAME=postgres
DB_PASSWORD=...
DB_DATABASE_NAME=immich
DATA_DIR=/data
CONFIG_DIR=/config

Then start the stack:

docker compose up -d

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