Immich

Deploys Immich — a self-hosted photo and video management solution — via Docker Compose, with machine learning, Valkey and PostgreSQL (VectorChord) included.

Requirements

• Docker
• community.docker Ansible collection (>=5.2.0)

Variables

Variable	Default	Description
immich_instance	immich	Unique instance name. Used as Compose project name and container names.
immich_data_path	/data/immich	Host path for persistent data (uploaded media, ML model cache, PostgreSQL data).
immich_docker_path	/docker/immich	Host path for the Compose file.
immich_version	v3.2.2	Immich image tag (server and machine learning). Pin to a specific release in production.
immich_db_version	14-vectorchord0.4.3-pgvectors0.2.0@sha256:…	PostgreSQL image tag (ghcr.io/immich-app/postgres). Take it from the upstream docker-compose.yml.
immich_db_storage_type	SSD	Storage type of the disk holding the PostgreSQL data: SSD or HDD. Selects the PostgreSQL tuning profile.
immich_redis_version	9@sha256:…	Valkey (Redis-compatible) image tag. Take it from the upstream docker-compose.yml.
immich_timezone	Europe/Berlin	Timezone (TZ database name) for all containers.
immich_domain	~	Public domain. When set, enables Traefik routing labels and attaches to the traefik_web network.
immich_traefik_certresolver	default	Traefik certificate resolver to use for immich_domain.
immich_port	~	When set, exposes Immich on this host port (maps to container port 2283). Omit when using immich_domain.
immich_db_pass	~	PostgreSQL password. Required. Only A-Za-z0-9 allowed. Generate with: openssl rand -hex 32
immich_uninstall	false	Stops and removes containers and the compose directory.
immich_purge	false	Also removes the data directory (including media and database). Requires immich_uninstall: true. Irreversible.

Usage

Minimal setup:

immich_db_pass: "{{ vault_immich_db_pass }}"
immich_domain: "photos.example.com"

Without a reverse proxy (direct host port instead of immich_domain):

immich_port: 2283

Taking over an existing install (pin the versions to what runs today):

immich_data_path: /path/to/existing/data
immich_version: v2.7.5
immich_db_version: 14-vectorchord0.3.0-pgvectors0.2.0

Uninstall

To stop and remove all containers and the compose directory:

immich_uninstall: true

Add immich_purge: true to also delete all uploaded media and the database.

Notes

• Upgrades. Bump immich_version and read the release notes first. When a release changes the PostgreSQL or Valkey image, update immich_db_version and immich_redis_version from that release's docker-compose.yml. VectorChord upgrades cannot be rolled back.
• Media location. Uploaded media lives in <immich_data_path>/uploads and is mounted at /data in the container, the layout of current Immich releases. An install that started on the older layout (/usr/src/app/upload) is migrated by Immich itself on the first start: it rewrites the file paths in its database in one transaction and nothing moves on disk. Take a database backup before that first run. The directory is owned by 1000:1000.
• Taking over an existing install. The role recreates the containers (names and network change) but keeps data and the database as they are, as long as immich_version and immich_db_version are pinned to what currently runs. The media directory is always mounted at /data (see above) and the cache is always Valkey, so an existing Redis container is replaced and starts empty: only queued background jobs are lost, and its old anonymous volume stays behind (docker volume rm). Old compose files in immich_docker_path are not removed; Compose prefers compose.yml, so move a leftover docker-compose.yml away.
• No hardware acceleration. Machine learning and transcoding run on CPU only. GPU acceleration needs the upstream hwaccel.*.yml files and a -cuda/-openvino/… image tag, which this role does not wire up.
• Postgres and Valkey are internal. Neither publishes a host port; they are only reachable on the instance's internal Docker network.
• Database healthcheck. The database uses the healthcheck of the PostgreSQL image instead of a plain pg_isready. The database is created with data checksums, and the image's check also reports the container as unhealthy once Postgres records a checksum failure. An unhealthy database fails the deploy and stops the server from starting after a recreate, so look into it first.
• Passwords are inlined. Secrets are rendered directly into compose.yml (mode 0600, root-only), like the other Docker roles. This is why immich_db_pass is restricted to A-Za-z0-9: characters such as $ would be interpreted by Compose.
• Containers are not proxied by Traefik unless immich_domain is set — it must already have a traefik_web network and a matching certresolver (see the traefik role).