Immich¶
Photo and video management.
| Runtime | Container (Docker Swarm), 4 containers: server, machine-learning, database, redis |
| Tier | Apps (Important) |
| Node | swarm-core |
| Image | ghcr.io/immich-app/immich-server:v3.0.3; ghcr.io/immich-app/immich-machine-learning:v3.0.3; ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0; valkey/valkey:9 |
| URL | https://immich.lab.riversfamily.uk |
| Auth | Native OIDC |
| Source | ansible/stacks/apps/immich/ |
Bumped from v1.124.2 to v3.0.3 (issue #105/PR #106): the stack structure
already matched v3 (server, machine-learning, database, redis; env names and
the 2283 port unchanged), so the update was the three Immich images plus the
cache moving from redis:6.2-alpine to valkey/valkey:9 (Immich v3 uses
Valkey; the service is still named redis, so REDIS_HOSTNAME is
unchanged), and the bundled Postgres image to
14-vectorchord0.4.3-pgvectors0.2.0.
Configuration¶
OIDC settings are not env vars — they are rendered into a mounted
immich-config.json (IMMICH_CONFIG_FILE=/config/immich-config.json), whose
oauth.clientSecret carries immich_oidc_client_secret. Once mounted,
settings in that file become read-only in the admin UI.
Machine learning runs CPU-only. GPU-backed ML would require moving Immich to
tier=media (the GPU is on swarm-media); it is deliberately kept on
tier=core for now.
Volumes¶
| Volume | Path | Backing | Contents |
|---|---|---|---|
upload |
/usr/src/app/upload |
Local | Original photos/videos |
model-cache |
/cache |
Local | ML models (machine-learning container) |
database |
/var/lib/postgresql/data |
Local | Postgres data — never NFS |
Networking¶
server joins both the shared traefik network (for its Traefik route)
and this stack's private internal network. machine-learning, database
and redis join internal only — they are unreachable from every other
stack.
Secrets¶
| Vault variable | Delivered as | Purpose |
|---|---|---|
vault_immich_db_password |
Swarm secret on database (POSTGRES_PASSWORD_FILE); server reads the same value inline |
Postgres password |
vault_immich_oidc_client_secret |
Rendered into immich-config.json |
OIDC client secret |
Gotchas¶
- Four containers — the most sidecars of any core/apps service besides NetBox and Paperless-ngx.
immich-config.jsonsettings become read-only in the admin UI once mounted; edit the template and re-deploy rather than through the UI.