Immich: Self-Hosted Photos with GPU Machine Learning
Purpose
Immich is a self-hosted photo and video management system built as a Google Photos replacement. It runs on the iGPU Docker host in a four-container compose stack: uploads, smart search, face recognition, and background processing all go through Traefik and ship logs to Graylog using the same pipeline as the rest of the lab.
Deployment
Immich runs on the iGPU Docker host, an LXC on the second Proxmox node with an Intel Iris Xe integrated GPU, not in Kubernetes. It moved there in November 2026 from the retired NVIDIA GPU Docker host (brief). The four containers are a compose stack kept in git and deployed by the compose fixer:
| Container | Image Role | Version |
|---|---|---|
immich_server | API, web UI, background jobs | ghcr.io/immich-app/immich-server:v3.3.5 |
immich_machine_learning | Face detection/recognition, CLIP smart search | ghcr.io/immich-app/immich-machine-learning:v3.3.5-openvino |
immich_postgres | Database with vector extensions for embeddings | ghcr.io/immich-app/postgres:14-vectorchord0.3.0-pgvectors0.2.0 |
immich_redis | Task queue and caching (Redis-compatible) | valkey/valkey:8-bookworm |
The ML container uses the OpenVINO variant, which runs inference on the integrated Intel GPU through the /dev/dri device. Immich ships its own Postgres image with vectorchord and pgvectors preloaded — no manual setup needed, unlike the SQL Server Postgres instance which runs in a separate VM with custom tuning.
GPU acceleration
The ML service handles two workloads on the integrated Intel GPU, through OpenVINO (the OpenVINOExecutionProvider):
- Face detection and recognition
- CLIP smart search, which does embedding-based semantic queries (“photos at the beach” without relying on tags).
Video transcoding now runs on Quick Sync. In a test, a video was transcoded to HEVC 720p and the log read “QSV-accelerated encoding and decoding” (brief).
Before the move, Immich’s video acceleration was never turned on, so transcoding ran on the CPU and the old discrete card did only the machine learning. Quick Sync is the first hardware transcoding this stack has had.
Architecture
flowchart LR
subgraph Clients
W["Web UI"]
M["Mobile App"]
end
subgraph Immich["Immich Containers (iGPU Docker Host)"]
S@{ img: "/assets/img/icons/immich.svg", label: "Server<br>v3.3.5", pos: "b", w: 40, h: 40, constraint: "on" }
ML["ML (OpenVINO)<br>v3.3.5-openvino"]
PG@{ img: "/assets/img/icons/postgresql.svg", label: "Postgres + vectors<br>14-vectorchord/pgvectors", pos: "b", w: 40, h: 40, constraint: "on" }
RK@{ img: "/assets/img/icons/valkey.svg", label: "Valkey 8<br>(Redis-compatible)", pos: "b", w: 40, h: 40, constraint: "on" }
end
subgraph Storage["Photo Library"]
L[Library]
end
S -->|queries| PG
S -->|tasks| RK
S -->|infer| ML
S -->|store/retrieve| L
G["Intel Iris Xe iGPU"]
ML -- "OpenVINO via /dev/dri" --> G
S -- "Quick Sync transcode (HEVC)" --> G
W & M -->|HTTPS via Traefik| S
subgraph Logging
GD@{ img: "/assets/img/icons/docker.svg", label: "gelf driver<br>(all 4 containers)", pos: "b", w: 40, h: 40, constraint: "on" }
GU["GELF UDP input"]
GP["Immich pipeline<br>(normalize levels + ANSIs)"]
GR@{ img: "/assets/img/icons/graylog.svg", label: "Graylog", pos: "b", w: 40, h: 40, constraint: "on" }
end
Immich --> GD --> GU --> GP --> GR
Configuration
Each container uses environment variables from the stack’s .env file. Notable settings:
- Server logs in JSON format, so every line is a structured record with level, context, pid, and stack fields — ready for Graylog to parse without extra configuration.
- ML has
NO_COLORset and an explicitly wideCOLUMNSvalue to suppress color codes from Python’s logging library. The framework still emits some residual escape sequences, so the log pipeline has to clean them up anyway.
The Postgres container uses the same internal Docker network as the others, with no external port exposure. Clients talk only to the server.
Storage
The photo library is bind-mounted into the containers from the host, not a Kubernetes PVC, so there is no storage class to configure.
Centralized Logging
All four containers send logs to Graylog via Docker’s native gelf log driver, reusing the same UDP input. Each container carries a node_name tag so Graylog can filter by host.
The Immich processing pipeline
A standalone Graylog pipeline processes Immich logs:
- Drop stray extractor fields — pre-existing extractors without conditions were catching Postgres timestamp lines and creating invalid date fields, which caused silent indexing failures.
- Parse per container — the server’s JSON log lines get unpacked into discrete fields (level, context, pid, stack trace) instead of staying as one big message blob.
- Clean ML ANSI codes and levels — even with
NO_COLOR, Python emits residual[2msequences. Docker’s GELF driver strips the leading escape byte but leaves the bracket code behind. The pipeline removes those remnants and normalizes level names (logtoinfo,warntowarning).
Gotcha: extractor without a condition
A Graylog extractor ran on every message instead of only matching ones it understood. Timestamp-prefixed Postgres lines hit the unconditional extractor, created invalid date fields, and got silently rejected at indexing — no error in the UI, no backpressure, just missing search results. The Immich pipeline’s first step drops this field before any other stage runs, preventing the same data loss for all four containers.
Access
The web UI routes through Traefik on the iGPU Docker host, behind a wildcard TLS certificate shared with internal homelab services. The mobile app uses the same Traefik route: the Immich server publishes no ports of its own on the host.
Authentication uses standard Immich user accounts — no SSO or external auth providers. The service lives at an internal subdomain of homelab.example, same pattern as everything else in this series.
Notes
- The ML image is now the
-openvinovariant. Same release, same CLIP model (ViT-B-32). - If you are weighing an iGPU against a discrete GPU for Immich: an Iris Xe handled both the ML and the video transcodes here. See also Frigate and Jellyfin and HandBrake, which moved with it.
- Valkey is a Redis drop-in replacement. Immich treats it like any other Redis connection — same protocol, newer maintenance.
- The custom Postgres image ships
vectorchordandpgvectorspreloaded, so container startup works without manual extension setup.