How imagegenius/docker-immich works
Project Type and Purpose
• This repository is a Docker image “builder” for Immich, a self-hosted photo/video backup solution.
• It packages Immich’s server and machine-learning microservice into a single container, orchestrated by s6-overlay, and provides CI/CD workflows to build, test, and publish multi-architecture Docker images.
High-Level Architectural Components
a. CI/CD Pipeline
• GitHub Actions workflows (.github/workflows) & Jenkinsfile
• Build triggers, cross-platform Docker manifest creation, image publishing
b. Docker Build Context
• Dockerfile / Dockerfile.aarch64 (multi-arch, multi-stage)
• s6-overlay files under root/etc/s6-overlay/s6-rc.d (service definitions)
• Entrypoint scripts, immich binaries at root/usr/local/bin
c. Runtime Container
• Process supervisor (s6-overlay)
• Services:
– init-check-variables, init-config-*, init-video-immich (initialization steps)
– svc-server (Immich web/API on 8080)
– svc-machine-learning (ML service on 3003)
– svc-microservices (composite service orchestration)
• CLI tools: immich, immich-admin
d. External Dependencies
• PostgreSQL (14–17) with VectorChord extension
• Valkey/Redis
• Optional hardware accelerators:
– Intel (via /dev/dri, cgroup rules, USB for OpenVINO)
– NVIDIA (via --runtime=nvidia or --gpus)
e. Volumes & Configuration
• /config (models, settings)
• /photos (user assets)
• /libraries (external libraries)
• Environment variables for DB, Redis, server/ML host & ports, PUID/PGID, TZ, etc.
Relationships and Data Flow
• CI/CD → Docker Build → Published Docker Image
• Container (s6) → runs initialization → starts server & ML services
• Immich Server ↔ PostgreSQL (DB_URL)
• Immich Server ↔ Redis (cache, jobs)
• Immich Server ↔ ML Service (HTTP API calls)
• Host volume mounts ↔ container directories (/config, /photos, /libraries)
• Host GPU or /dev/dri ↔ container ML for hardware acceleration
Key Architectural Patterns & Principles
• Process supervision (s6-overlay) inside a single container to manage multiple services
• Separation of concerns: init steps vs main services vs CLI
• Externalize state: use volumes for config, data, models
• Environment-driven configuration for maximum flexibility
• CI/CD for reproducible, versioned, multi-arch container images
• Modular service definitions (s6-rc.d folders) for easy extension