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).
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 permission | Used for |
|---|---|
user.read | Checking the account and connection |
asset.read | Metadata, asset details and timeline selection |
asset.statistics | Counting pictures with people |
asset.view | Thumbnails and video playback |
asset.download | Downloading original media, including for a render worker |
face.read | Face boxes |
person.read | People, their details and thumbnails |
person.statistics | Picture counts for a person |
album.read | Finding albums |
map.search | Finding the home country from Immich's own map data |
| Optional read permission | Used for |
|---|---|
tag.read | Finding generated films through the tag index. Add it: it keeps large libraries fast |
stack.read | Keeping one picture from each stack instead of selecting its members separately |
| Optional upload permission | Used for |
|---|---|
asset.upload | Uploading the film and checking for duplicate uploads |
tag.create | Creating or finding the app's generated-film tag |
tag.asset | Attaching that tag to the film, its release and day tags, and its type, year and story tags when upload.film_tags is on |
asset.update | Writing the film's description (its title and story summary). Without it the film still uploads and replaces its earlier render, with no description |
album.create | Creating the destination album |
albumAsset.create | Adding 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.
| Want | Setup |
|---|---|
| GPU picture preparation | Inference service, docker-compose.gpu.yml |
| Image captions | Caption server, docker-compose.gpu.yml |
| A text model | Reader |
| Faster video encoding | Hardware encoding |
| Rendering on another box | Render worker |
| Generated music | Music |
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.