Skip to main content

Compose setup files

Every release, release candidates included, publishes these files beside its deployment bundle. Download them from the same release: example.env and every image default carry its version.

FilePurpose
docker-compose.ymlThe Basic app on 127.0.0.1:22830 (4 GB memory limit), its config and store volume, and ./output
example.envImmich connection, IMMICH_MEMORIES_VERSION, tier, GPU box and reader inputs
docker-compose.gpu.ymlGPU tier: the inference service, a one-shot download of the pinned caption weights and the caption server; raises the app's limit to 8 GB
docker-compose.full.ymlFull tier; add after the GPU file, with a reader enabled
docker-compose.cuda.ymlCUDA images for inference and captions, with NVIDIA device access
docker-compose.gpu-worker.ymlThe unified inference, caption and render worker, on its own GPU box
docker-compose.postgres.ymlA PostgreSQL 16 store with its own volume; the app waits for it to be healthy
Basic is one container. GPU adds inference and captions; Full connects your reader.

Select the files​

The base file runs Basic alone and publishes the web UI on host port 22830 (8080 inside the container), bound to 127.0.0.1. To reach it from another machine, set UI_BIND_ADDRESS; sign-in is on by default. For NVIDIA, add the GPU and CUDA files from the same release; Full also needs its tier file and a reader. The matching tab in Quick start has the downloads.

GPU:

docker compose -f docker-compose.yml -f docker-compose.gpu.yml -f docker-compose.cuda.yml up -d

Full:

docker compose -f docker-compose.yml -f docker-compose.gpu.yml -f docker-compose.full.yml -f docker-compose.cuda.yml up -d

You can put that selection in .env instead, so updates use plain docker compose up -d:

COMPOSE_FILE=docker-compose.yml:docker-compose.gpu.yml:docker-compose.cuda.yml

Without the CUDA file, the GPU file's images run on the CPU, which is only useful for diagnosis. The CUDA file needs the NVIDIA Container Toolkit and a GPU the container can see. Picking a tier doesn't prove the hardware works: preflight reports inference compute separately from video encoding and warns when acceleration is missing, without changing the tier.

Reader and Settings​

For Full, set all three in .env before starting:

READER_ENABLED=true
READER_URL=http://reader-box:8000/v1
READER_MODEL=your-server-model-name
# Optional, when the reader requires authentication:
READER_API_KEY=your-reader-key

A URL and model alone never enable the reader. Docker Full needs an external reader: the image doesn't include the local reader runtime. A native install can leave the URL blank once that runtime and its model are installed. The same reader inputs work on Basic for titles and music mood, without turning Basic selection into Full.

The Compose files pass these to the app as IMMICH_MEMORIES_DEPLOYMENT_* variables, with the suffixes TIER, GPU_BOX, INFERENCE_URL, CAPTION_URL, READER_URL, READER_MODEL, READER_API_KEY and READER_ENABLED. TIER is the tier, ranked like an environment variable, so .env and a config file can't disagree. The others are defaults: saved Settings, YAML and normal environment overrides win, so the service URLs and reader stay editable in Settings. A normal override such as IMMICH_MEMORIES_LLM__BASE_URL wins over Settings too, and locks that field there. Native and Kubernetes recipes can set the service URLs directly; an empty inference URL keeps inference in the app.

Remote GPU box​

The worker file needs IMMICH_URL and a shared RENDER_WORKER_TOKEN. It publishes port 8092 on localhost only; set GPU_WORKER_BIND_ADDRESS to open it to a private LAN or VPN, and restrict which machines can reach it. The render token doesn't protect the inference and caption routes, and the pictures sent there are your library.

The NAS app uses the base file, with this block in its .env:

TIER=gpu
GPU_BOX=192.168.1.50

That points inference at port 8092 on that address and captions at /v1 on the same address. A hostname, an IPv6 address or an explicit port (GPU_BOX=gpu-box:9000) also work. Local fallback stays on. Rendering is set separately: the worker URL ending in /render and its token go in the render worker settings.

PostgreSQL​

The base file uses SQLite. Add docker-compose.postgres.yml only if you want a PostgreSQL store, and set POSTGRES_PASSWORD in .env. For an existing SQLite install, follow the copy-first procedure before enabling the app database URL.