Post

Immich: Self-Hosted Photos with GPU Machine Learning

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:

ContainerImage RoleVersion
immich_serverAPI, web UI, background jobsghcr.io/immich-app/immich-server:v3.3.5
immich_machine_learningFace detection/recognition, CLIP smart searchghcr.io/immich-app/immich-machine-learning:v3.3.5-openvino
immich_postgresDatabase with vector extensions for embeddingsghcr.io/immich-app/postgres:14-vectorchord0.3.0-pgvectors0.2.0
immich_redisTask 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_COLOR set and an explicitly wide COLUMNS value 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:

  1. Drop stray extractor fields — pre-existing extractors without conditions were catching Postgres timestamp lines and creating invalid date fields, which caused silent indexing failures.
  2. 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.
  3. Clean ML ANSI codes and levels — even with NO_COLOR, Python emits residual [2m sequences. Docker’s GELF driver strips the leading escape byte but leaves the bracket code behind. The pipeline removes those remnants and normalizes level names (log to info, warn to warning).

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 -openvino variant. 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 vectorchord and pgvectors preloaded, so container startup works without manual extension setup.
This post is licensed under CC BY 4.0 by the author.