# imagegenius/docker-immich architecture

> Architecture diagram of the GitHub repository imagegenius/docker-immich, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/imagegenius/docker-immich
- Repository: https://github.com/imagegenius/docker-immich

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CI/CD Layer
    subgraph "CI/CD Pipeline"
        direction TB
        GithubActions["GitHub Actions Workflows"]:::ci
        Jenkins["Jenkinsfile"]:::ci
    end
    GithubActions -->|"triggers build"| DockerBuild
    Jenkins -->|"triggers build"| DockerBuild

    %% Docker Build Context
    subgraph "Docker Build Context" 
        direction TB
        Dockerfile["Dockerfile"]:::build
        DockerfileAarch["Dockerfile.aarch64"]:::build
        S6Overlay["s6-overlay root"]:::build
        S6Defs["s6-rc.d service definitions"]:::build
    end
    DockerBuild["Docker Build"]:::ci --> Dockerfile
    DockerBuild --> DockerfileAarch
    DockerBuild --> S6Overlay
    DockerBuild --> S6Defs
    DockerBuild -->|"produces image"| DockerImage["Docker Image"]:::ci

    %% Runtime Container
    DockerImage --> RuntimeContainer
    subgraph "Container Runtime" 
        direction TB
        Supervisor["s6 Supervisor"]:::runtime
        Supervisor --> InitServices
        Supervisor --> MainServices
        Supervisor --> CLITools

        subgraph "Initialization Services" 
            direction TB
            initCheck["init-check-variables"]:::runtime
            initConfigImmich["init-config-immich"]:::runtime
            initVideoImmich["init-video-immich"]:::runtime
            initConfigEnd["init-config-end"]:::runtime
            initTestRun["init-test-run"]:::runtime
        end
        InitServices --> initCheck
        InitServices --> initConfigImmich
        InitServices --> initVideoImmich
        InitServices --> initConfigEnd
        InitServices --> initTestRun

        subgraph "Main Services"
            direction TB
            svcServer["svc-server: Immich API (8080)"]:::runtime
            svcML["svc-machine-learning: ML Service (3003)"]:::runtime
            svcMicro["svc-microservices"]:::runtime
        end
        MainServices --> svcServer
        MainServices --> svcML
        MainServices --> svcMicro

        svcServer -->|"calls ML API"| svcML

        subgraph "CLI Tools"
            direction TB
            immichCLI["immich CLI"]:::runtime
            immichAdmin["immich-admin CLI"]:::runtime
        end
        CLITools --> immichCLI
        CLITools --> immichAdmin
    end

    %% External Services
    subgraph "External Dependencies"
        direction TB
        PostgreSQL["PostgreSQL (14-17)"]:::external
        Redis["Redis"]:::external
    end
    svcServer -->|"DB connection"| PostgreSQL
    svcServer -->|"cache/jobs"| Redis

    %% Host Volumes & Devices
    subgraph "Host Resources"
        direction TB
        configVol["/config"]:::host
        photosVol["/photos"]:::host
        librariesVol["/libraries"]:::host
        devDRI["/dev/dri"]:::host
        GPU["GPU Runtime"]:::host
    end
    configVol --> RuntimeContainer
    photosVol --> RuntimeContainer
    librariesVol --> RuntimeContainer
    devDRI --> RuntimeContainer
    GPU --> RuntimeContainer

    %% Click Events
    click GithubActions "https://github.com/imagegenius/docker-immich/blob/main/.github/workflows/*.yml"
    click Jenkins "https://github.com/imagegenius/docker-immich/tree/main/Jenkinsfile"
    click Dockerfile "https://github.com/imagegenius/docker-immich/tree/main/Dockerfile"
    click DockerfileAarch "https://github.com/imagegenius/docker-immich/blob/main/Dockerfile.aarch64"
    click S6Overlay "https://github.com/imagegenius/docker-immich/tree/main/root/etc/s6-overlay"
    click S6Defs "https://github.com/imagegenius/docker-immich/blob/main/root/etc/s6-overlay/s6-rc.d"
    click initCheck "https://github.com/imagegenius/docker-immich/tree/main/root/etc/s6-overlay/s6-rc.d/init-check-variables"
    click initConfigImmich "https://github.com/imagegenius/docker-immich/tree/main/root/etc/s6-overlay/s6-rc.d/init-config-immich"
    click initVideoImmich "https://github.com/imagegenius/docker-immich/tree/main/root/etc/s6-overlay/s6-rc.d/init-video-immich"
    click initConfigEnd "https://github.com/imagegenius/docker-immich/tree/main/root/etc/s6-overlay/s6-rc.d/init-config-end"
    click initTestRun "https://github.com/imagegenius/docker-immich/tree/main/root/etc/s6-overlay/s6-rc.d/init-test-run"
    click svcServer "https://github.com/imagegenius/docker-immich/tree/main/root/etc/s6-overlay/s6-rc.d/svc-server"
    click svcML "https://github.com/imagegenius/docker-immich/tree/main/root/etc/s6-overlay/s6-rc.d/svc-machine-learning"
    click svcMicro "https://github.com/imagegenius/docker-immich/tree/main/root/etc/s6-overlay/s6-rc.d/svc-microservices"
    click immichCLI "https://github.com/imagegenius/docker-immich/tree/main/root/usr/local/bin/immich"
    click immichAdmin "https://github.com/imagegenius/docker-immich/tree/main/root/usr/local/bin/immich-admin"

    %% Styles
    classDef ci fill:#D0E8FF,stroke:#0477BF,color:#0477BF
    classDef build fill:#B3E5FC,stroke:#0288D1,color:#01579B
    classDef runtime fill:#C8E6C9,stroke:#388E3C,color:#1B5E20
    classDef external fill:#FFE0B2,stroke:#F57C00,color:#E65100
    classDef host fill:#EEEEEE,stroke:#757575,color:#424242
```
