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.
| Layer | System boundary | Main assurance |
|---|---|---|
| Server and CLI | HTTP APIs, database state, queues, WebSockets, and the CLI | Cross-service and command behavior |
| Web | Browser flows against the running web and server services | User-facing product behavior |
| UI | Browser behavior with controlled network data | Complex client views and state changes |
| Maintenance | Backup and maintenance behavior through API and browser paths | Operational 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
| Trigger | Consequence | Guard |
|---|---|---|
| The test server starts before PostgreSQL is healthy | API and CLI tests fail during setup or use incomplete state | Compose waits for the database health check before starting the test server |
| The server never emits its running message | Local Vitest setup waits until its timeout and the environment remains unusable | The setup has a 60-second timeout and CI uses Compose readiness waiting |
| A test does not wait for a queue or WebSocket event | Assertions race with background processing and fail intermittently | Shared helpers poll queue state and wait for event IDs or counts |
| A release tag or device variant is missing from the build matrix | A published deployment cannot pull the expected image | Workflow tag rules and matrix builds cover release and accelerator variants |
| The release Compose file is taken from a different source revision than the images | Operators can get incompatible service versions | Use the Compose file published with the selected release |
Key files
| File | Why to read it |
|---|---|
| docker/docker-compose.yml | Defines the standard release service relationship and persistent resources. |
| docker/docker-compose.dev.yml | Shows the local development composition and its extra web and initialization stages. |
| docker/docker-compose.rootless.yml | Shows the reduced-privilege deployment contract. |
server/Dockerfile | Shows how the main release image assembles the application and build identity. |
machine-learning/Dockerfile | Shows how device-specific inference images keep one service interface. |
| .github/…/docker.yml | Defines image build, tag, platform, and publication behavior. |
| e2e/docker-compose.yml | Defines the isolated release-like test environment. |
| e2e/docker-compose.dev.yml | Defines the test environment for local development images. |
| e2e/package.json | Defines the commands that select API, CLI, maintenance, web, and UI validation layers. |
| e2e/playwright.config.ts | Maps browser test projects to the running web system. |
| e2e/…/docker-compose.ts | Controls local test environment startup and cleanup. |
| e2e/…/utils.ts | Provides the shared cross-service actions and readiness waits used by tests. |
| .github/…/test.yml | Defines CI execution, runner coverage, and failure artifacts for end-to-end suites. |