Introducing a new way to review your PRs.

Read the announcement

immich-app / immich

High performance self-hosted photo and video management solution.

View on GitHub

21 documents · Updated Oct 19, 2026

docs / deployment-and-end-to-end-validation

Deployment and end-to-end validation

Immich uses Docker Compose to run its server, machine-learning service, data store, and job store as one product environment. Release images are built from the same service boundaries that the end-to-end harness starts, so the tests can check behavior across APIs, workers, the web app, the database, and event streams. This page complements Developer contracts and extension ecosystem.

Deployment composition

Runtime composition

The production deployment joins the Immich server with machine learning, Valkey, and PostgreSQL. The server exposes the main product entry point and uses the other services for stored state, background work, and media analysis. Persistent media, database state, model data, and monitoring data live outside the short-lived containers.

The development deployment adds a separate web service and an initialization service. This split supports fast local changes while keeping the same core service relationships as production.

flowchart LR
    Client[Client] --> Server[Immich server]
    Server --> Database[(PostgreSQL)]
    Server --> Redis[(Valkey)]
    Server --> ML[Machine learning]
    Server --> Media[(Media volume)]
    Server --> Web[Web service in development]

References: docker/docker-compose.yml• L10-78 docker/docker-compose.dev.yml• L14-177

Deployment variants

The Compose files express three operating goals rather than three different products:

  • The release composition runs published server and machine-learning images.
  • The production composition builds both application images locally and adds Prometheus and Grafana for service metrics.
  • The rootless composition keeps the same product roles while running services as an unprivileged user with reduced capabilities.

The release Compose file is version-sensitive. Operators must use the file published for the selected release instead of assuming that the file on the main branch matches an older image set.

References: docker/docker-compose.yml• L1-18 docker/docker-compose.prod.yml• L10-107 docker/docker-compose.rootless.yml• L10-97 docker/README.md• L1-5

Release build configuration

Application image assembly

The server image is the release unit for the main application. Its build joins the SDK, plugin SDK, server, web client, CLI, and core plugin outputs into one runnable image. The image also records its source revision and build identity so a running service can be traced back to the build that produced it.

The machine-learning image is selected by a device target. That target controls the runtime used for CPU, GPU, or accelerator-specific inference while keeping the service boundary stable for the server.

References: server/Dockerfile• L12-55 server/Dockerfile• L57-127 machine-learning/Dockerfile• L68-84 machine-learning/Dockerfile• L151-207

Release image publication

The Docker workflow decides which image families need a build from the changed paths. It then builds server and machine-learning images for their supported platforms, applies branch, pull-request, commit, and release tags, and mirrors published release tags to Docker Hub. A release is treated as complete only after the required image jobs pass their final success checks.

This flow makes image tags part of the deployment contract. A change that affects a service image must preserve the mapping between build context, device variant, platform, and release tag.

References: .github/…/docker.yml• L38-71 .github/…/docker.yml• L154-200 .github/…/docker.yml• L202-272

End-to-end validation

Isolated test environment

The end-to-end environment gives tests a private server, database, Valkey instance, and test asset set. The web variant adds the web service and routes it to the test server. The environment uses fixed test credentials and ports so API, CLI, browser, database, and WebSocket checks can share one controlled system.

The harness starts the environment only when it is not already available. It waits for the server to report that its microservices are running, then removes the Compose environment after the test run. This makes local runs convenient while allowing CI to start the environment once and reuse it across test groups.

sequenceDiagram
    participant Tests
    participant Compose
    participant Services as Test services
    participant System as Immich system

    Tests->>Compose: Start or reuse environment
    Compose->>Services: Start database, Valkey, server, and web
    Services->>System: Report readiness
    Tests->>System: Send API, CLI, browser, and event actions
    System-->>Tests: Return state and events
    Tests->>Compose: Stop and remove environment

References: e2e/docker-compose.yml• L1-69 e2e/docker-compose.dev.yml• L1-80 e2e/…/docker-compose.ts• L4-34 e2e/vitest.config.ts• L3-25

Validation layers

The harness checks different product boundaries with tools suited to each boundary. Vitest runs the server, CLI, and maintenance checks, while Playwright runs the web, maintenance, and UI browser projects through separate commands.

LayerSystem boundaryMain assurance
Server and CLIHTTP APIs, database state, queues, WebSockets, and the CLICross-service and command behavior
WebBrowser flows against the running web and server servicesUser-facing product behavior
UIBrowser behavior with controlled network dataComplex client views and state changes
MaintenanceBackup and maintenance behavior through API and browser pathsOperational workflows

The shared test utilities create users and assets, reset state, call the generated SDK, wait for queue completion, and observe WebSocket events. These helpers let tests assert eventual results instead of assuming that an upload or background job finishes immediately.

References: e2e/package.json• L7-21 e2e/playwright.config.ts• L16-68 e2e/…/utils.ts• L83-130 e2e/…/utils.ts• L160-228 e2e/…/utils.ts• L236-303 e2e/…/utils.ts• L657-693

CI validation

Continuous integration runs the end-to-end suites on both x86 and Arm runners when relevant paths change. It builds the test services, runs server and CLI checks, then runs browser, UI, and maintenance checks. It stores Docker logs and browser reports so a failed cross-service run can be diagnosed after the job ends.

The API suite uses real service state for flows such as asset upload and event delivery. The browser suite covers actions such as registration and onboarding. The UI suite uses generated data and mock network routes where it needs stable, high-volume view state.

References: .github/…/test.yml• L464-541 .github/…/test.yml• L543-658 e2e/…/asset.e2e-spec.ts• L40-100 e2e/…/auth.e2e-spec.ts• L4-46 e2e/…/asset-viewer.e2e-spec.ts• L17-57

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep service names, internal host names, and exposed test ports aligned between both end-to-end Compose files and the test configuration.
  • Keep image build arguments for source identity aligned with the release metadata shown by the running services.
  • Keep machine-learning device variants aligned across the Dockerfile, Compose hardware options, and the release workflow matrix.
  • Keep test readiness checks aligned with the server health signal and database health signal. A running container is not the same as a ready service.
  • Keep generated SDK setup available before tests that use SDK calls or CLI commands.
  • Keep event and queue waits aligned with the asynchronous work that each test starts.

Important failure modes

TriggerConsequenceGuard
The test server starts before PostgreSQL is healthyAPI and CLI tests fail during setup or use incomplete stateCompose waits for the database health check before starting the test server
The server never emits its running messageLocal Vitest setup waits until its timeout and the environment remains unusableThe setup has a 60-second timeout and CI uses Compose readiness waiting
A test does not wait for a queue or WebSocket eventAssertions race with background processing and fail intermittentlyShared helpers poll queue state and wait for event IDs or counts
A release tag or device variant is missing from the build matrixA published deployment cannot pull the expected imageWorkflow tag rules and matrix builds cover release and accelerator variants
The release Compose file is taken from a different source revision than the imagesOperators can get incompatible service versionsUse the Compose file published with the selected release

Key files

FileWhy to read it
docker/docker-compose.ymlDefines the standard release service relationship and persistent resources.
docker/docker-compose.dev.ymlShows the local development composition and its extra web and initialization stages.
docker/docker-compose.rootless.ymlShows the reduced-privilege deployment contract.
server/DockerfileShows how the main release image assembles the application and build identity.
machine-learning/DockerfileShows how device-specific inference images keep one service interface.
.github/…/docker.ymlDefines image build, tag, platform, and publication behavior.
e2e/docker-compose.ymlDefines the isolated release-like test environment.
e2e/docker-compose.dev.ymlDefines the test environment for local development images.
e2e/package.jsonDefines the commands that select API, CLI, maintenance, web, and UI validation layers.
e2e/playwright.config.tsMaps browser test projects to the running web system.
e2e/…/docker-compose.tsControls local test environment startup and cleanup.
e2e/…/utils.tsProvides the shared cross-service actions and readiness waits used by tests.
.github/…/test.ymlDefines CI execution, runner coverage, and failure artifacts for end-to-end suites.