📸 Immich — Photo Library & Machine Learning

Host: Homelab · Compose: Homelab/Immich/compose.yaml
Stack name: immich

1. Overview

Immich is a self-hosted photo and video backup solution with machine learning features: face recognition, CLIP-based smart search, and object detection. This stack also includes Immich Kiosk for displaying a rotating photo slideshow, commonly used on a family display or tablet.

Hardware-accelerated ML inference is enabled via /dev/dri (Intel/AMD iGPU).

2. Architecture & Services

Service	Image	Port	Role
`immich-server`	`immich-app/immich-server:v2.7.5`	`2283`	Main API, web UI, and upload endpoint
`immich-machine-learning`	`immich-app/immich-machine-learning:v2.7.5`	—	Facial recognition, CLIP embeddings, object detection
`database`	`immich-app/postgres:14-vectorchord`	—	PostgreSQL with pgvectors for ML similarity search
`redis`	`valkey/valkey:8-bookworm`	—	Session cache and job queue
`immich-kiosk`	`damongolding/immich-kiosk:0.39.3`	`3097`	Photo slideshow for display screens

3. Networking

background — Internal network connecting all Immich services (ML, DB, Redis, Kiosk).
apps / backend — External shared networks for inter-stack communication.
cloudflare-net — External network routing the main server through Cloudflare Tunnel to photos.m1ckyb.com.
Traefik labels are present on immich-server for internal routing at immich.home-lab.micky.id.au.

4. Persistent Storage

Container	Host Path / Env Var	Description
`database`	`${DB_DATA_LOCATION}`	PostgreSQL data directory
`immich-server`	`${UPLOAD_LOCATION}`	Uploaded photos and videos
`immich-machine-learning`	`model-cache` (named vol)	Downloaded ML model weights

Both DB_DATA_LOCATION and UPLOAD_LOCATION are defined in the .env file.

5. Environment Variables

Loaded from .env for all services. Key variables:

Variable	Service	Description
`DB_DATA_LOCATION`	`database`	Host path for PostgreSQL data
`DB_PASSWORD`	`database`	PostgreSQL password
`DB_USERNAME`	`database`	PostgreSQL user
`DB_DATABASE_NAME`	`database`	Database name
`UPLOAD_LOCATION`	`immich-server`	Host path for media uploads
`REDIS_HOSTNAME`	`immich-server`	Redis container name
`KIOSK_IMMICH_API_KEY`	`immich-kiosk`	API key to access Immich
`KIOSK_IMMICH_URL`	`immich-kiosk`	`https://photos.m1ckyb.com/`
`KIOSK_PERSON`	`immich-kiosk`	Comma-separated person IDs for the slideshow
`KIOSK_REFRESH`	`immich-kiosk`	Slide change interval (seconds)

6. Access & Usage

URL	Description
`https://photos.m1ckyb.com`	Immich web UI (public, via Cloudflare Tunnel)
`https://immich.home-lab.micky.id.au`	Internal Traefik route
`http://localhost:3097`	Kiosk slideshow display

# Start the stack
docker compose -f Homelab/Immich/compose.yaml up -d

# Health check
curl -f http://localhost:2283/api/server/ping

# Check ML service
docker logs immich_machine_learning -f

7. Maintenance & Backup

# Update (check release notes first — DB migrations may run)
docker compose -f Homelab/Immich/compose.yaml pull
docker compose -f Homelab/Immich/compose.yaml up -d

# Backup uploads and DB
rsync -av ${UPLOAD_LOCATION} /backup/immich/media/
docker exec immich_postgres pg_dump -U ${DB_USERNAME} ${DB_DATABASE_NAME} | gzip > /backup/immich/db.sql.gz

[!WARNING] Always update Immich as a complete set — never update only immich-server or only immich-machine-learning. Mismatched versions will break the ML API. Check the Immich release notes for DB migration steps before upgrading.