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

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
# 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.3 publish both 1.2.3 and v1.2.3 image tags.
  • Other stable releases retain their version tags without changing latest. Rerunning an older release does not automatically move latest backwards.
  • Prereleases publish their full version tags, such as 1.2.3-rc.1, without updating latest.
  • edge follows development builds from master after 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