05-immich.md

kstack: book: Centerpoint Home Lab chapter: Media & Entertainment page: Immich tags: [immich, photos, media, cuda, gpu, self-hosted]

Overview

Immich is the self-hosted photo and video library for the homelab — a local alternative to Google Photos. It provides automatic mobile backup, face recognition, smart search, and album management. The machine learning container runs on the RTX 5080 via CUDA for accelerated facial recognition and CLIP-based smart search.

Photo storage lives on the UnRAID NAS NFS mount at /mnt/Photos.

Access

Type	URL	Notes
Internal	https://photos.home.local	LAN access via Step-CA TLS
External	https://photos.jeevesconsults.ca	GeoBlock (CA/US/IN) + CrowdSec — no Authentik ForwardAuth

Immich uses its own user authentication — Authentik ForwardAuth is not applied because it would break the mobile app OAuth flow.

Containers in This Stack

Container	Image	GPU	Role
immich_server	ghcr.io/immich-app/immich-server:release	No	Main API and web server
immich_machine_learning	ghcr.io/immich-app/immich-machine-learning:release-cuda	Yes	Face recognition + CLIP search
immich_postgres	ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0	No	PostgreSQL with pgvecto.rs
immich_redis	valkey/valkey:8-bookworm	No	Job queue and cache

Configuration

Compose file: /home/jeeves/docker/immich/docker-compose.yml Compose project: immich

Ports

Port	Protocol	Purpose
2283	TCP	Immich web UI and API (host-bound)

Traefik Labels

# External route
traefik.http.routers.immich.rule: Host(`photos.jeevesconsults.ca`)
traefik.http.routers.immich.entrypoints: websecure
traefik.http.routers.immich.tls.certresolver: letsencrypt
traefik.http.routers.immich.middlewares: plex-geoblock@file,crowdsec-bouncer@file,immich-headers
traefik.http.middlewares.immich-headers.headers.customrequestheaders.X-Forwarded-Proto: https

# Internal route
traefik.http.routers.immich-internal.rule: Host(`photos.home.local`)
traefik.http.routers.immich-internal.entrypoints: websecure
traefik.http.routers.immich-internal.tls.certresolver: step-ca

traefik.http.services.immich.loadbalancer.server.port: 2283

Key Environment Variables (.env file)

Variable	Value / Notes
UPLOAD_LOCATION	/mnt/Photos/immich-library
DB_HOSTNAME	immich_postgres
DB_USERNAME	postgres
DB_PASSWORD	REDACTED
DB_DATABASE_NAME	immich
REDIS_HOSTNAME	immich_redis
TZ	America/Toronto
IMMICH_VERSION	release (pinned to latest stable)

Volumes / Bind Mounts

Host Path / Volume	Container Path	Purpose
/mnt/Photos/immich-library	/data	Primary upload library (NFS)
/mnt/Photos/Plex	/mnt/Photos/Plex:rw	Plex photo library (external library)
/mnt/Photos/Google_Photos	/mnt/Photos/Google_Photos:rw	Google Photos import folder
/etc/localtime	/etc/localtime:ro	Host timezone sync
model-cache (named volume)	/cache	ML model weight cache (machine learning container)
${DB_DATA_LOCATION} (from .env)	/var/lib/postgresql/data	PostgreSQL data

Sub-section: Machine Learning (CUDA)

immich_machine_learning runs with runtime: nvidia, giving it access to the RTX 5080 for:

• Face detection and recognition — identifies and clusters faces across the library
• CLIP embeddings — powers smart search ("photos of dogs at the beach")

Environment Variable	Value	Purpose
NVIDIA_VISIBLE_DEVICES	all	GPU access
NVIDIA_DRIVER_CAPABILITIES	compute,utility	CUDA compute caps
MACHINE_LEARNING_DEVICE_ID	0	Use GPU device 0

ML model files are cached in the model-cache named Docker volume. Models are downloaded from HuggingFace on first use and cached for subsequent runs.

Sub-section: PostgreSQL (pgvecto.rs)

Immich uses a custom PostgreSQL 14 image with the pgvecto.rs and pgvectors extensions pre-installed. These extensions power the vector similarity search that underlies CLIP smart search and face clustering.

ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0

The shm_size: 128mb allocation is required for PostgreSQL's shared memory.

Sub-section: Redis / Valkey

immich_redis uses Valkey (the Redis fork) as the job queue and cache backend. It handles background job scheduling for ML processing, thumbnail generation, and library scans.

Dependencies

• NFS mounts /mnt/Photos (UnRAID) must be healthy
• immich_postgres → immich_redis → immich_server startup order
• NVIDIA container runtime for immich_machine_learning

Notes / Gotchas

• Immich does not use Authentik ForwardAuth — it has built-in multi-user auth. The mobile app connects directly to https://photos.jeevesconsults.ca.
• The X-Forwarded-Proto: https header (immich-headers middleware) is required for Immich to generate correct share links and OAuth callbacks.
• The PostgreSQL image is pinned to a specific digest — do not change it arbitrarily. Immich releases are tied to specific database schema versions.
• Library scan and ML job processing can be CPU/GPU intensive. Schedule large library scans during off-peak hours via Admin → Jobs.
• External libraries (Plex photos, Google Photos) are read-only imports. Changes to files in these directories are picked up on the next library scan.

---

Last Updated: 2026-06-16