Immich with Docker Compose

High performance self-hosted photo and video management solution. In the project's words: Immich README checked 2026-09-23

Add Immich to the builder to use your own domain, get its passwords generated in your browser, and combine it with other apps in one file.

What Immich needs

Only figures Immich's own documentation publishes, each linked to the page it is on. Where the project gives no number, this page does not invent one.

Resource	Minimum	Recommended
RAM	6 GB	8 GB
	With 4 GB, Immich can run only with machine learning (face and smart search) disabled. If you set Docker resource limits, the Postgres container needs at least 2 GB of its own. Source: Immich docs: Requirements checked 2026-09-23
CPU	2 cores	4 cores
	amd64 or arm64 only. Since v3 the machine-learning container on amd64 needs the x86-64-v2 level, which most CPUs released since about 2012 have. Source: Immich docs: Requirements checked 2026-09-23
Disk	Not published by the project
	No size is published. Thumbnails and transcoded video add 10-20% to the size of the library on average; the Postgres files are typically 1-3 GB and should be on local SSD, never a network share. Source: Immich docs: Requirements checked 2026-09-23

On top of this, Caddy (the reverse proxy in the file) is a single small container. Immich itself runs as 4 containers: immich-server, immich-machine-learning, immich-redis, immich-database.

docker-compose.yml

This is exactly what the builder writes for Immich alone on example.org: the official definition with its published ports removed and Caddy added in front. Every ${VARIABLE} is defined in the .env below.

# docker-compose.yml built at dankhost.com for: Immich
# Each app block is its official compose definition. Only the names were prefixed with
# the app slug (services, containers, volumes, bind folders, .env variables) so any set of
# apps can share one file; other differences are listed under "Changed:" in each block.
# Only Caddy publishes ports. Secrets live in .env next to this file.

services:
  # ---- Caddy: the one reverse proxy, HTTPS certificates from Let's Encrypt ----
  # Source: https://caddyserver.com/docs/running (checked 2026-09-23)
  # Source: https://github.com/dani-garcia/vaultwarden/wiki/Using-Docker-Compose (checked 2026-09-23)
  # Caddyfile goes in ./caddy/Caddyfile. Fixed address 172.30.0.2 so apps can trust it exactly.
  caddy:
    image: "caddy:2"
    container_name: "caddy"
    restart: "unless-stopped"
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"
    volumes:
      - "./caddy:/etc/caddy"
      - "caddy-data:/data"
      - "caddy-config:/config"
    networks:
      proxy:
        ipv4_address: "172.30.0.2"

  # ---- Immich (photos.example.org) ----
  # Source: https://docs.immich.app/install/docker-compose/ (checked 2026-09-23)
  # Source: https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml (checked 2026-09-23)
  # Source: https://github.com/immich-app/immich/releases/latest/download/example.env (checked 2026-09-23)
  # Source: https://docs.immich.app/install/environment-variables/ (checked 2026-09-23)
  # Source: https://docs.immich.app/administration/reverse-proxy/ (checked 2026-09-23)
  # Changed: Removed the documented '2283:2283' port; Caddy reaches immich-server on the proxy network.
  #          The documented 'env_file: .env' is replaced by explicit environment entries for the same variables, so one .env can serve several apps without name clashes.
  #          The documented example DB_PASSWORD 'postgres' is replaced by a generated letters-and-digits secret (Immich asks for A-Za-z0-9 only).
  #          Added IMMICH_TRUSTED_PROXIES (from Immich's environment-variable list) set to Caddy's fixed address.
  #          The internal network is not marked internal: the machine-learning container downloads its models from the internet on first use.
  immich-server:
    image: "ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}"
    container_name: "immich-server"
    volumes:
      - "${IMMICH_UPLOAD_LOCATION}:/data"
      - "/etc/localtime:/etc/localtime:ro"
    environment:
      DB_PASSWORD: "${IMMICH_DB_PASSWORD}"
      DB_USERNAME: "${IMMICH_DB_USERNAME}"
      DB_DATABASE_NAME: "${IMMICH_DB_DATABASE_NAME}"
      IMMICH_TRUSTED_PROXIES: "172.30.0.2"
    depends_on:
      - "immich-redis"
      - "immich-database"
    restart: "always"
    healthcheck:
      disable: false
    networks:
      proxy: {}
      immich-backend: {}
  immich-machine-learning:
    image: "ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}"
    container_name: "immich-machine-learning"
    volumes:
      - "immich-model-cache:/cache"
    restart: "always"
    healthcheck:
      disable: false
    networks:
      immich-backend: {}
  immich-redis:
    image: "docker.io/valkey/valkey:9@sha256:70739f85ad2ee01a726a965584a0f94895f01b0c60b3cc8b0aeef11eaa6888cf"
    container_name: "immich-redis"
    healthcheck:
      test: "redis-cli ping | grep -q PONG || exit 1"
    restart: "always"
    networks:
      immich-backend:
        aliases:
          - "redis"
  immich-database:
    image: "ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0@sha256:bcf63357191b76a916ae5eb93464d65c07511da41e3bf7a8416db519b40b1c23"
    container_name: "immich-database"
    environment:
      POSTGRES_PASSWORD: "${IMMICH_DB_PASSWORD}"
      POSTGRES_USER: "${IMMICH_DB_USERNAME}"
      POSTGRES_DB: "${IMMICH_DB_DATABASE_NAME}"
      POSTGRES_INITDB_ARGS: "--data-checksums"
    volumes:
      - "${IMMICH_DB_DATA_LOCATION}:/var/lib/postgresql/data"
    shm_size: "128mb"
    restart: "always"
    healthcheck:
      disable: false
    networks:
      immich-backend:
        aliases:
          - "database"

networks:
  # Pinned so the trusted-proxy address given to each app (172.30.0.2) is exact.
  # If "docker compose up" reports "Pool overlaps", change 172.30.0 here, in Caddy's
  # ipv4_address and in every trusted-proxy value to a free 172.x.0 range.
  proxy:
    ipam:
      config:
        - subnet: "172.30.0.0/24"
          ip_range: "172.30.0.128/25"
          gateway: "172.30.0.1"
  immich-backend: {}

volumes:
  caddy-data:
  caddy-config:
  immich-model-cache:

Caddyfile save as caddy/Caddyfile

Caddy gets and renews the HTTPS certificate for photos.example.org by itself once the DNS record points at your server and ports 80 and 443 reach it.

# Caddyfile built at dankhost.com. Save it as ./caddy/Caddyfile next to docker-compose.yml.
# Caddy gets and renews a Let's Encrypt certificate for each name below by itself,
# once the DNS records point at this server and ports 80 and 443 reach it.

# Immich
photos.example.org {
	reverse_proxy immich-server:2283
}

.env

The secret is left blank here on purpose: a password printed on a public page is the same for everyone who copies it. The builder fills it with random letters and digits made in your browser.

# .env for Immich, from dankhost.com/app/immich/. Fill the blank secret before starting.
# Keep this file private (chmod 600).

# Immich
IMMICH_VERSION=v3
IMMICH_UPLOAD_LOCATION=./immich/library
IMMICH_DB_DATA_LOCATION=./immich/postgres
# 32 random letters and digits: the builder fills this in your browser
IMMICH_DB_PASSWORD=
IMMICH_DB_USERNAME=postgres
IMMICH_DB_DATABASE_NAME=immich

Changes from the official file

Besides prefixing every service, container, volume, folder and variable with immich (so any set of apps can share one file), these are all the differences from what the project documents:

Removed the documented '2283:2283' port; Caddy reaches immich-server on the proxy network.
The documented 'env_file: .env' is replaced by explicit environment entries for the same variables, so one .env can serve several apps without name clashes.
The documented example DB_PASSWORD 'postgres' is replaced by a generated letters-and-digits secret (Immich asks for A-Za-z0-9 only).
Added IMMICH_TRUSTED_PROXIES (from Immich's environment-variable list) set to Caddy's fixed address.
The internal network is not marked internal: the machine-learning container downloads its models from the internet on first use.

Notes for Immich behind the proxy

Open the photos address straight after 'docker compose up -d': the first account created becomes the admin.
Photos land in ./immich/library and the database in ./immich/postgres (the .env locations). Immich says network shares are not supported for the database folder.

How to run it

At your DNS provider, add an A record named photos on your domain pointing at the server's public IP address, and forward TCP 80, TCP 443 and UDP 443 to it.
Save the three files in one folder: docker-compose.yml and .env side by side, the Caddyfile at ./caddy/Caddyfile. Replace example.org with your domain in the Caddyfile, the compose file and the .env, or let the builder do it.
Fill the blank IMMICH_DB_PASSWORD in .env. The builder generates it; on the server, tr -dc A-Za-z0-9 </dev/urandom | head -c 32 prints 32 random letters and digits. Then chmod 600 .env.

Start it:

docker compose up -d
docker compose logs -f caddy   # watch the certificate arrive

Open the new address (photos. plus your domain) in a browser and follow the notes above.

Back it up

Immich publishes a backup procedure: a database dump plus a copy of UPLOAD_LOCATION, best taken with immich-server stopped so the two stay in sync.

Below is the BACKUP.md the builder writes next to the compose file above: which of its folders and volumes hold data, the dump command the project documents, rewritten for this file's service names, what to copy with which container stopped, and a restore check. Pick more apps in the builder and it covers them all in one file.

# BACKUP.md built at dankhost.com for: Immich

What to copy from the docker-compose.yml built with this file, the database dump each project documents (rewritten for the service names in that file), what to copy with which container stopped, and how to check the result. Run every command in the folder that holds docker-compose.yml.

The folders are owned by the containers' users: put sudo in front of tar if it says "Permission denied". Named volumes live under /var/lib/docker/volumes, not next to the compose file, so they are copied through a throwaway ubuntu container (Docker's documented --volumes-from method). tar makes a full copy each run; for large folders an incremental tool (restic, borg, rsync) saves time and space.

Never run "docker compose down -v" on this file: it deletes the named volumes of every app in it.

## Before you start

    BACKUP=/mnt/backup/selfhost   # change this: a disk or machine other than this server's system disk
    mkdir -p "$BACKUP"

## Every time: the three stack files

    tar czf "$BACKUP/stack-files.tar.gz" docker-compose.yml .env caddy

.env holds the database passwords and secret keys the apps were set up with; keep this archive as private as the data.

## Caddy (the reverse proxy)

Caddy's docs: 'The data directory must not be treated as a cache.' It holds the TLS certificates and their private keys; without it Caddy has to ask Let's Encrypt for every certificate again.

- caddy-data (named volume, /data in caddy)
  BACK UP: TLS certificates, private keys, OCSP staples.
- caddy-config (named volume, /config in caddy)
  SKIP: the last active configuration, kept for 'caddy run --resume', which this setup does not use: it starts from the Caddyfile.
- ./caddy (/etc/caddy in caddy)
  IN stack-files.tar.gz: the Caddyfile, copied with the stack files above.

Copy (Caddy keeps serving while you copy):

    docker run --rm --volumes-from caddy -v "$BACKUP":/backup ubuntu tar cvf /backup/caddy-data.tar /data

Restore check:

    tar tf "$BACKUP/caddy-data.tar" > /dev/null && echo OK
    docker run --rm --volumes-from caddy -v "$BACKUP":/backup ubuntu bash -c "cd /data && tar xvf /backup/caddy-data.tar --strip 1"

Sources:
- Caddy docs: Conventions, Data directory: https://caddyserver.com/docs/conventions#data-directory (checked 2026-09-24)
- Docker docs: Volumes, Back up, restore, or migrate data volumes: https://docs.docker.com/engine/storage/volumes/#back-up-restore-or-migrate-data-volumes (checked 2026-09-24)

## Immich

Immich publishes a backup procedure: a database dump plus a copy of UPLOAD_LOCATION, best taken with immich-server stopped so the two stay in sync.

What this compose mounts:
- ./immich/library (${IMMICH_UPLOAD_LOCATION} in .env, /data in immich-server)
  BACK UP: everything Immich stores as files: upload/ and library/ (your originals), profile/ (avatars), thumbs/ and encoded-video/ (Immich can regenerate these), and backups/ (Immich's own nightly database dumps, 14 kept by default).
- immich-model-cache (named volume, /cache in immich-machine-learning)
  SKIP: downloaded machine-learning models; Immich's backup page does not list it.
- ./immich/postgres (${IMMICH_DB_DATA_LOCATION} in .env, /var/lib/postgresql/data in immich-database)
  COVERED BY THE COMMAND BELOW: Postgres data files; copy them only with the database stopped.

1. Stop immich-server. Immich's backup page: stopping immich-server while you back up means nothing changes, so the database and the files always match. The database keeps running for the dump.

    docker compose stop immich-server

2. Database dump for immich-database:

    docker compose exec -T immich-database pg_dump --clean --if-exists --dbname=immich --username=postgres | gzip > "$BACKUP/immich-database.sql.gz"

   This is the current command on Immich's Backup and Restore page, with immich_postgres replaced by this file's service name and the database name and user from this .env. Immich's pages for v2.5.0 and older used pg_dumpall --clean --if-exists --username=<DB_USERNAME> instead (every database on the server); a dump made that way is restored with --dbname=postgres.

3. Copy while immich-server is stopped:

    tar czf "$BACKUP/immich-library.tar.gz" ./immich/library

4. Start it again:

    docker compose start immich-server

Restore check:

    zcat "$BACKUP/immich-database.sql.gz" | grep -c 'PostgreSQL database dump complete'   # 1 means pg_dump finished
    tar tzf "$BACKUP/immich-library.tar.gz" > /dev/null && echo OK

Put a copy back (with immich-server stopped):

    tar xzf "$BACKUP/immich-library.tar.gz"   # recreates ./immich/library; move the old folder aside first

Immich recommends restoring from its web app: Administration > Maintenance > Restore database backup, or 'Restore from backup' on the welcome screen of a fresh install whose upload folder already holds the restored files. Its command-line restore, with this file's names, into a database that immich-server has never started against:

    docker compose create
    docker compose start immich-database
    sleep 10
    gunzip --stdout "$BACKUP/immich-database.sql.gz" | sed "s/SELECT pg_catalog.set_config('search_path', '', false);/SELECT pg_catalog.set_config('search_path', 'public, pg_catalog', true);/g" | docker compose exec -T immich-database psql --dbname=immich --username=postgres --single-transaction --set ON_ERROR_STOP=on
    docker compose up -d

Immich's own restore starts with 'docker compose down -v'. Do not run that on this combined file: it deletes the named volumes of every app in it. If the database has already run, stop the Immich services and empty ./immich/postgres instead, as Immich's note on resetting DB_DATA_LOCATION says.

Sources:
- Immich docs: Backup and Restore: https://docs.immich.app/administration/backup-and-restore/ (checked 2026-09-24)
- Immich docs as of v2.5.0: Backup and Restore (the older pg_dumpall command): https://github.com/immich-app/immich/blob/v2.5.0/docs/docs/administration/backup-and-restore.md (checked 2026-09-24)

Sources

Every page below was fetched on the date shown.

Immich README checked 2026-09-23 (what it does)
Immich docs: Requirements checked 2026-09-23 (hardware requirements)
Immich docs: Docker Compose install checked 2026-09-23 (compose definition and proxy settings)
Immich release docker-compose.yml checked 2026-09-23 (compose definition and proxy settings)
Immich release example.env checked 2026-09-23 (compose definition and proxy settings)
Immich docs: environment variables (DB_HOSTNAME, REDIS_HOSTNAME, IMMICH_TRUSTED_PROXIES) checked 2026-09-23 (compose definition and proxy settings)
Immich docs: reverse proxy (Caddy example) checked 2026-09-23 (compose definition and proxy settings)
Caddy docs: Keep Caddy running (Docker Compose section) checked 2026-09-23 (Caddy)
Vaultwarden wiki: Caddy with HTTP challenge (uses the caddy:2 image) checked 2026-09-23 (Caddy)
Immich docs: Backup and Restore checked 2026-09-24 (backup plan)
Immich docs as of v2.5.0: Backup and Restore (the older pg_dumpall command) checked 2026-09-24 (backup plan)
Caddy docs: Conventions, Data directory checked 2026-09-24 (backup plan)
Docker docs: Volumes, Back up, restore, or migrate data volumes checked 2026-09-24 (backup plan)

Add Immich to the builder All twenty apps