📸 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
`database`	`ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0@sha256:41eacbe83eca995561fe43814fd4891e16e39632806253848efaf04d3c8a8b84`	—	PostgreSQL with pgvectors for ML similarity search
`immich-kiosk`	`ghcr.io/damongolding/immich-kiosk:0.43.2`	`3097`	Photo slideshow for display screens
`immich-machine-learning`	`ghcr.io/immich-app/immich-machine-learning:v3.2.2`	—	Facial recognition, CLIP embeddings, object detection
`immich-server`	`ghcr.io/immich-app/immich-server:v3.2.2`	`2283`	Main API, web UI, and upload endpoint
`redis`	`docker.io/valkey/valkey:8-bookworm@sha256:fea8b3e67b15729d4bb70589eb03367bab9ad1ee89c876f54327fc7c6e618571`	—	Session cache and job queue

3. Networking

apps — —
backend — —
background — Internal network connecting all Immich services (ML, DB, Redis, Kiosk).
cloudflare-net — External network routing the main server through Cloudflare Tunnel to photos.m1ckyb.com.

4. Persistent Storage

| Container | Host Path / Volume | Description | |---|---|---|| | database | ${DB_DATA_LOCATION} | PostgreSQL data directory | | immich-machine-learning | model-cache | — | | immich-server | ${UPLOAD_LOCATION} | Uploaded photos and videos | | immich-server | /etc/localtime | — |

5. Environment Variables

Variable	Service	Description
`POSTGRES_DB`	`database`	—
`POSTGRES_INITDB_ARGS`	`database`	—
`POSTGRES_PASSWORD`	`database`	—
`POSTGRES_USER`	`database`	—
`KIOSK_BACKGROUND_BLUR`	`immich-kiosk`	—
`KIOSK_CACHE`	`immich-kiosk`	—
`KIOSK_DATE_FORMAT`	`immich-kiosk`	—
`KIOSK_DISABLE_UI`	`immich-kiosk`	—
`KIOSK_DISBALE_SCREENSAVER`	`immich-kiosk`	—
`KIOSK_IMAGE_DATE_FORMAT`	`immich-kiosk`	—
`KIOSK_IMAGE_FIT`	`immich-kiosk`	—
`KIOSK_IMAGE_TIME_FORMAT`	`immich-kiosk`	—
`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)
`KIOSK_SHOW_DATE`	`immich-kiosk`	—
`KIOSK_SHOW_IMAGE_DATE`	`immich-kiosk`	—
`KIOSK_SHOW_IMAGE_TIME`	`immich-kiosk`	—
`KIOSK_SHOW_PROGRESS`	`immich-kiosk`	—
`KIOSK_SHOW_TIME`	`immich-kiosk`	—
`KIOSK_TIME_FORMAT`	`immich-kiosk`	—
`KIOSK_TRANSITION`	`immich-kiosk`	—
`TZ`	`immich-kiosk`	—

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.