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_serverstartup 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: httpsheader (immich-headersmiddleware) 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