Skip to main content

Docker Compose

Docker Compose is the recommended container install: the app runs beside your existing Immich server. Basic is one container; GPU and Full add model services. You need Docker Compose v2 and 4 GB free for the app. On a NAS, check the NAS notes for folder permissions and device access.

Install​

Follow Quick start and select Basic, GPU or Full. It covers the release files, Immich connection, access, model preparation and first film. For a single file to paste into a stack editor, use the setup builder.

This page covers running that install. Installation help has port, permissions and startup fixes.

Reaching the UI from another machine​

The shipped mapping is 127.0.0.1:22830:8080: only the host can reach it. From your desktop, a tunnel needs no port change:

ssh -L 8080:localhost:22830 you@your-server

Open http://localhost:8080 on the desktop.

The app asks for a sign-in on first start and generates a password for it: read the username and password in docker logs immich-memories (where it lives).

For LAN access, set this in .env:

UI_BIND_ADDRESS=0.0.0.0

To choose your own sign-in instead of the generated one, add IMMICH_MEMORIES_AUTH_USERNAME and IMMICH_MEMORIES_AUTH_PASSWORD next to it.

UI_BIND_ADDRESS is the switch: the shipped mapping is ${UI_BIND_ADDRESS:-127.0.0.1}:22830:8080, so there is no need to edit it. Run docker compose up -d, then open http://your-server:22830. If that host port is taken, change only the number before the final :8080, for example 22831:8080. Keep the bind address and container port.

To check that sign-in is on, call a protected route without logging in, from another machine:

curl -s -o /dev/null -w '%{http_code}\n' http://your-server:22830/api/v1/settings

It answers 401 without an app session and 200 with one. /health/ready is anonymous on purpose: it reports the app version and overall readiness, while detailed connection results require a session when authentication is enabled. Use the protected settings route to check authentication.

This port speaks plain HTTP: the password and session cookie cross your LAN in the clear. For TLS, put a reverse proxy in front and keep UI_BIND_ADDRESS=127.0.0.1 (Authentication).

This app can access your library

Sign-in is on by default, with a generated password. Keep it on before exposing the port. Keep one UI replica.

For OIDC or a proxy with HTTPS, see Authentication.

Stack editor LAN access​

The builder's Single file for a stack editor output has no .env. Before deploying it on a trusted LAN, you can keep the generated sign-in (the password is in docker logs immich-memories) or choose your own by setting these entries directly under the app service's existing environment::

IMMICH_MEMORIES_AUTH_USERNAME: admin
IMMICH_MEMORIES_AUTH_PASSWORD: replace-with-your-own-long-password

Choose a password of at least 12 characters. In the same app service, change its ports: entry from 127.0.0.1:22830:8080 to 0.0.0.0:22830:8080 (keep your chosen host port if it differs). Deploy the stack, open http://your-server-address:22830, and sign in. The container manager's login does not protect this port. This is HTTP on your LAN; for encrypted access, keep localhost and use the SSH tunnel above or HTTPS proxy setup.

The API key​

In Immich, open Account Settings > API Keys > New API Key. Select these ten read permissions to make films. Add the upload set only on the account that receives finished films. Partner accounts need the read set only.

Read permissionUsed for
user.readChecking the account and connection
asset.readMetadata, asset details and timeline selection
asset.statisticsCounting pictures with people
asset.viewThumbnails and video playback
asset.downloadDownloading original media, including for a render worker
face.readFace boxes
person.readPeople, their details and thumbnails
person.statisticsPicture counts for a person
album.readFinding albums
map.searchFinding the home country from Immich's own map data
Optional read permissionUsed for
tag.readFinding generated films through the tag index. Add it: it keeps large libraries fast
stack.readKeeping one picture from each stack instead of selecting its members separately
Optional upload permissionUsed for
asset.uploadUploading the film and checking for duplicate uploads
tag.createCreating or finding the app's generated-film tag
tag.assetAttaching that tag to the film, its release and day tags, and its type, year and story tags when upload.film_tags is on
asset.updateWriting the film's description (its title and story summary). Without it the film still uploads and replaces its earlier render, with no description
album.createCreating the destination album
albumAsset.createAdding the film to the album

asset.delete is separate and optional. It lets the app move a previous render of the same recipe to Immich's trash after the replacement succeeds. It never authorizes a hard delete through this app. Originals are not changed.

stack.read is separate and optional too. It lets the app fold a stack (an edit and its original, a burst) into its top picture before selection, so only one of them ships, and a star on any picture of the stack counts for it. Without it, GET /stacks answers 403, the run logs one warning for that account, and every stacked picture is read as its own candidate.

Timeline routes use asset.read; there is no additional timeline.read requirement. Album-update permissions are not needed. The app reads the key's own permission list through GET /api-keys/me, which needs API-key authentication but no extra permission.

Tagged films are excluded from source footage across every page of results. Add tag.read to each account's key: it makes that check use the tag index, which keeps large libraries fast. Without it, the app checks video tags one by one through asset.read, but only on videos taken within the film's dates, so a large library stays workable. Uploading and tagging a film uses tag.create and tag.asset, independently of this optional read permission.

Run immich-memories preflight or immich-memories config test after creating the key. A missing read permission is an error naming the missing permissions, and a cut will not start.

Missing upload rights leave the film usable. The Render panel explains why its upload option is unavailable. If upload was requested through the CLI, saved settings or automation, the film is still rendered and kept locally; the run reports what could not be uploaded and offers Download. The CLI prints the local path.

With partial upload rights, the app performs the permitted steps and reports the missing ones. For example, asset.upload without tag permissions can upload a film but cannot mark it as this app's own. On Immich v3 that untagged film could be selected as source footage later. The local film is kept whenever uploading, tagging or album filing is incomplete. Without asset.delete, the new upload can succeed and the previous version stays in Immich.

All is not recommended: that key can change or delete the whole library. Existing All keys continue to work, but preflight warns and points back to this smaller permission set.

Using the CLI​

The CLI is inside the container. Commands elsewhere in these docs use this prefix:

docker compose exec immich-memories immich-memories generate --year 2025 --month 6

An optional alias saves typing:

alias im='docker compose exec immich-memories immich-memories'
im preflight

Films into Immich​

Local films appear in ./output. The web Render panel has an upload checkbox. To upload CLI and daily films by default, add this to the service's environment: block:

IMMICH_MEMORIES_UPLOAD__ENABLED: "true"
IMMICH_MEMORIES_UPLOAD__ALBUM_NAME: "Memories"

Run docker compose up -d. A line in .env alone does not pass an arbitrary variable to the container. Environment variables explains the rule. After confirmed upload, the local film and its run directory are removed. What Immich sees lists the writes.

Next to your Immich stack​

You can put the immich-memories service in Immich's Compose file. Add immich-memories-config: to its top-level volumes:, set IMMICH_URL=http://immich-server:2283, and add depends_on: [immich-server]. The service then reaches Immich over that stack's internal network.

Add-on services​

For a fresh GPU or Full installation, use the tier tab in Quick start. The guides below cover changing individual services on an existing install.

Basic is one container. GPU adds inference and captions; Full connects your reader.
WantSetup
GPU picture preparationInference service, docker-compose.gpu.yml
Image captionsCaption server, docker-compose.gpu.yml
A text modelReader
Faster video encodingHardware encoding
Rendering on another boxRender worker
Generated musicMusic

Reaching a model server​

A server on the Docker host is host.docker.internal, not localhost:

For an existing install, set the reader URL to http://host.docker.internal:8000/v1 and the caption URL to http://host.docker.internal:8092/v1 in Settings. Full also needs the reader's served model and explicit enable switch. The setup builder supplies those values as editable defaults for a fresh install.

Docker Desktop resolves that name. On Linux, add this to the service and have the model server listen on an address reachable from the bridge, such as 0.0.0.0:

extra_hosts:
- "host.docker.internal:host-gateway"

The product tier in compose​

The base requests Basic through TIER=basic. The GPU and Full tier files request their respective tiers. Preflight checks whether the selected hardware and services can satisfy that request. TIER outranks a tier saved in Settings or written in config.yaml; change the tier in .env. See tier requirements. Keep IMMICH_MEMORIES_EDITORIAL__PREPARATION__DETECTOR_CACHE_DIR on the persistent volume when writing your own service block, so detector downloads survive a recreate.

Resources​

The default 4 GB limit suits 1080p. Use 8 GB for 4K on GPU/Full; Basic stays capped at 1080p. The file sets no CPU quota because Synology kernels can refuse cpus:. Use cpuset if needed.

Daily automation​

Add these two lines to the service's environment: block, set TZ in .env, and recreate:

IMMICH_MEMORIES_AUTOMATION__ENABLED: "true"
IMMICH_MEMORIES_AUTOMATION__DAILY_AT: "09:00"

The running UI makes one eligible memory a day, no cron needed. Automate it covers selection, uploads, retries and external triggers.

Health check and logs​

docker inspect --format='{{.State.Health.Status}}' immich-memories
docker compose logs -f immich-memories

The image probes /health/live; monitoring should use /health/ready. Diagnostics covers per-run logs and preflight.

What to keep​

Keep the named config volume and ./output. The expensive data is store.db: prepared facts, people, settings, review decisions and run history. Back up the store and keep any IMMICH_MEMORIES_SECRET_KEY you use for saved credentials.

The store: SQLite or PostgreSQL​

SQLite on the config volume is the default. You do not need PostgreSQL to make films. Database and backups covers both backends and moving an install.

Updating​

Follow Upgrading: back up, pull the image, recreate, fetch the current model pins and run preflight.

Disk​

The preview cache defaults to 30 GB (about 0.3 MB per picture your films reach), the video and prepared-source caches to 10 GB each, and past cut attempts to 5 GB. Uploaded films are removed locally after confirmed delivery; local-only or failed deliveries keep their files. Storage and caches covers sizing and cleanup.

Hardening​

Run with a read-only root filesystem

The shipped file has no hardening block. Add this to the app service:

security_opt:
- no-new-privileges:true
cap_drop:
- ALL
read_only: true
tmpfs:
- /tmp:size=2G
- /home/immich/.cache:size=1G

The persistent config volume keeps the session signing key. For 4K, allow more temporary space (8 GB, say); intermediates can exceed 2 GB. Tmpfs uses memory, so size it with the container limit in mind.

Custom music​

Upload a track in the web Render panel. For CLI runs, bind-mount a music directory and use --music /app/music/track.mp3.

Add this alongside the app's existing volumes: entries, then run docker compose up -d:

- ./music:/app/music:ro

Put track.mp3 in ./music on the host:

docker compose exec immich-memories immich-memories generate --year 2025 --music /app/music/track.mp3

Building the image​

For a source checkout, make docker fills in the version and git metadata. The normal install uses the published image. INSTALL_EXTRAS=none make docker builds a slim image without the classifiers needed for films.

Stop or remove this installation​

Stop, reset and uninstall separates retaining data for reinstall from deleting app state.