# Docker Compose

Markdown version of <https://sam-dumont.github.io/immich-memories/docs/run/docker/>.

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](https://sam-dumont.github.io/immich-memories/docs/run/requirements.md). On a NAS, check the
[NAS notes](https://sam-dumont.github.io/immich-memories/docs/run/nas.md) for folder permissions and device access.

## Install

Follow [Quick start](https://sam-dumont.github.io/immich-memories/docs/get-started/quick-start.md) 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](https://sam-dumont.github.io/immich-memories/setup/).

This page covers running that install. [Installation help](https://sam-dumont.github.io/immich-memories/docs/reference/installation-help.md)
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](https://sam-dumont.github.io/immich-memories/docs/run/authentication.md#the-generated-password)).

For LAN access, set this in `.env`:

```ini
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](https://sam-dumont.github.io/immich-memories/docs/run/authentication.md)).

> **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](https://sam-dumont.github.io/immich-memories/docs/run/authentication.md).

### 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:`:

```yaml
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](#reaching-the-ui-from-another-machine) or
[HTTPS proxy setup](https://sam-dumont.github.io/immich-memories/docs/run/authentication.md#behind-a-reverse-proxy-with-tls).

## 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:

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

An optional alias saves typing:

```bash
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:

```yaml
      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](https://sam-dumont.github.io/immich-memories/docs/run/environment-variables.md) explains the rule.
After confirmed upload, the local film and its run directory are removed.
[What Immich sees](https://sam-dumont.github.io/immich-memories/docs/run/privacy.md#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](https://sam-dumont.github.io/immich-memories/docs/get-started/quick-start.md).
The guides below cover changing individual services on an existing install.

**Diagram: Basic is one container. GPU adds inference and captions; Full connects your reader.** [(image)](https://sam-dumont.github.io/immich-memories/diagrams/deploy-compose.svg)

```text
┌───────────────────────────┐
│                           │
│      immich-memories      │
│host port → container :8080│
│       config + store      │
│    named config volume    │
│           Films           │
│          ./output         │
└───────────────────────────┘
              │
              │
              ├─────────────────────────┬───────────────────────┐
              │                         │                       │
              ▼                         ▼                       ▼
┌───────────────────────────┐  ┌─────────────────┐  ┌───────────────────────┐
│                           │  │                 │  │                       │
│         inference         │  │                 │  │                       │
│   container + host :8092  │  │                 │  │                       │
│         captioner         │  │   postgres:16   │  │     GPU box :8092     │
│container :8092, host :8094│  │no published port│  │facts, captions, render│
│       caption models      │  │                 │  │                       │
│     one-shot download     │  │                 │  │                       │
└─────────────┬─────────────┘  └─────────────────┘  └───────────────────────┘
              │
              │
              │
              │
              ▼
┌───────────────────────────┐
│                           │
│      Existing reader      │
│     URL + served model    │
└───────────────────────────┘
```

Groups:

- Basic: the whole app · docker-compose.yml · CPU, rules, up to 1080p
  - immich-memories; config + store; Films
- - GPU tier: captions and checks · docker-compose.gpu.yml · docker-compose.cuda.yml · NVIDIA driver and Container Toolkit
  * inference; captioner; caption models
- - Full tier · docker-compose.full.yml · connect and enable your reader
  * Existing reader
- - PostgreSQL, any tier · docker-compose.postgres.yml · the store moves off SQLite
  * postgres:16
- Or: GPU work on another private machine · docker-compose.gpu-worker.yml · set GPU\_BOX on the app; rendering takes its own URL
  - GPU box :8092

Arrows:

- immich-memories; config + store; Films → inference; captioner; caption models
- immich-memories; config + store; Films → postgres:16
- immich-memories; config + store; Films → GPU box :8092
- inference; captioner; caption models → Existing reader

| Want | Setup |
| - | - |
| GPU picture preparation | [Inference service](https://sam-dumont.github.io/immich-memories/docs/better/inference.md), `docker-compose.gpu.yml` |
| Image captions | [Caption server](https://sam-dumont.github.io/immich-memories/docs/better/captions.md), `docker-compose.gpu.yml` |
| A text model | [Reader](https://sam-dumont.github.io/immich-memories/docs/better/reader.md) |
| Faster video encoding | [Hardware encoding](https://sam-dumont.github.io/immich-memories/docs/run/hardware.md) |
| Rendering on another box | [Render worker](https://sam-dumont.github.io/immich-memories/docs/better/gpu-render.md) |
| Generated music | [Music](https://sam-dumont.github.io/immich-memories/docs/better/music.md) |

### 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](https://sam-dumont.github.io/immich-memories/setup/) 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`:

```yaml
    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](https://sam-dumont.github.io/immich-memories/docs/run/requirements.md#the-preparation-tier).
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](https://sam-dumont.github.io/immich-memories/docs/run/nas.md#do-not-use-cpus-on-a-synology).

## Daily automation

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

```yaml
      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](https://sam-dumont.github.io/immich-memories/docs/make/automate.md) covers selection, uploads, retries and external triggers.

## Health check and logs

```bash
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](https://sam-dumont.github.io/immich-memories/docs/run/maintenance/health-logs-cache.md) 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](https://sam-dumont.github.io/immich-memories/docs/run/database.md#managing-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](https://sam-dumont.github.io/immich-memories/docs/run/database.md) covers both backends and moving an install.

## Updating

Follow [Upgrading](https://sam-dumont.github.io/immich-memories/docs/run/maintenance/upgrading.md#docker): 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](https://sam-dumont.github.io/immich-memories/docs/run/maintenance/health-logs-cache.md#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:

```yaml
    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`:

```yaml
      - ./music:/app/music:ro
```

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

```bash
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](https://sam-dumont.github.io/immich-memories/docs/run/lifecycle.md) separates retaining data for reinstall from deleting app state.
