Skip to main content

On a NAS

Choose your container manager and follow its install steps:

PlatformInstall
Synology DSMContainer Manager project
UnraidDocker template or Compose Manager
TrueNAS 24.10+Custom app
PortainerDocker Standalone stack
QNAP or another NAS with ComposeDocker Compose

Basic runs on the NAS CPU. GPU uses NVIDIA inference and captions, either on a supported host or a separate GPU machine. Full adds a reader. Each stack-editor guide includes the builder's three tier choices. Allow memory and storage in addition to what Immich uses: requirements.

The generated single-file route uses Docker-managed volumes. It does not need a hand-created output folder. The release Compose file uses ./output; use the permissions below for that route, or when choosing a NAS share for films.

Existing model services​

If you already run separate inference and caption services, including in Kubernetes, reuse them. In your platform's builder, choose GPU or Full and enter the inference host and port in GPU box address, such as 192.168.1.50:8092. This exports an app-only Compose file. In its app environment, replace IMMICH_MEMORIES_DEPLOYMENT_GPU_BOX with both URLs:

IMMICH_MEMORIES_DEPLOYMENT_INFERENCE_URL: http://192.168.1.50:8092
IMMICH_MEMORIES_DEPLOYMENT_CAPTION_URL: http://192.168.1.51:8092/v1

Use your services' private addresses, reachable from the NAS. Kubernetes-internal service names usually cannot be reached from there. Skip the generated GPU-worker files and commands: those would start another worker. Inference and captions explain the two services.

For Full, enter the reader's /v1 URL and served model name in the builder. It enables the reader; replace the generated reader-key placeholder, or empty it if the server needs no key. The reader needs a 32k context.

This app-only file keeps the base memory: 4G limit. Keep output at 1080p with that limit. For 4K on GPU/Full, raise the app limit to 8G and allow that RAM on the NAS. The model services need their own memory. Laya still runs in the app; remote inference does not move rendering. After starting, use Download models in the app and run immich-memories preflight in its container, as your platform guide describes.

NAS operating notes​

Storage, network access, encoding and resource tuning. For first startup, use the platform guide above, then make a film.

The output folder​

The image runs as UID/GID 1000. NAS users often have a different UID, so preflight can report Output directory is not writable. The fix depends on the NAS.

Synology DSM. chown alone does nothing useful on a home share: the share's Synology ACL still denies uid 1000. Add an ACL entry for it, and a second one for your own DSM user, over SSH as that user, no sudo, in the project folder:

mkdir -p output
/usr/syno/bin/synoacltool -addace output user:1000:allow:rwxpdDaARWc--:fd--
/usr/syno/bin/synoacltool -addace output user:$(id -un):allow:rwxp-DaARWc--:fd--
/usr/syno/bin/synoacltool -getace output
ls -ld output

Both entries go in. ls -ld output should end in + and not show d---------+: that means the ACL holds only uid 1000 and your own account gets "Permission denied" on touch output/x.

  • synoacltool is not on a docker-group user's PATH, so use the full path.
  • -addace takes numeric ids. -add user:1000 resolves names and answers "No such user".
  • The fd flags make the entry inherit, so files the container creates stay readable and deletable by your own DSM user.
  • Your own entry is not guaranteed. A new output folder made after chmod 700 . is in plain Linux mode, so the first -addace creates an ACL with only uid 1000 in it. The second line puts your account back ($(id -un) is your DSM user name).

With both entries, the uid-1000 container writes its films through the bind mount and your own DSM user can read and remove them.

Plain Linux NAS (no Synology ACLs):

sudo chown -R 1000:1000 output

Don't set user: "<your uid>:<gid>" in the Compose file. The image's /home/immich is 0700 and owned by 1000, so the app crashes at start with PermissionError: ... '/home/immich/.immich-memories'.

If you replace a named output volume with this bind mount, earlier runs show the film as unavailable: their files stayed in the old volume. Nothing is broken, new films land in output. Keep either a bind mount or a named volume at /app/output, including when upload-back is enabled. An interrupted or failed upload needs that local copy to survive container replacement.

Reaching the UI​

The default host port, 22830, is local to the NAS. From your desktop:

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

Open http://localhost:8080 on the desktop. If SSH forwarding is denied, the browser cannot reach the app through that tunnel. For LAN access without a tunnel, set UI_BIND_ADDRESS=0.0.0.0 in .env (the sign-in is on by default; its generated password is in docker logs immich-memories): Docker access recipe. That port is plain HTTP; use the proxy route if you want TLS.

The shipped Compose file uses host port 22830 and the container name immich-memories. If another NAS app already uses that port, change the host port in the mapping and tunnel to it. The container port remains 8080. For a second installation, give this project a different container_name and host port. Run commands from its project folder with docker compose exec immich-memories immich-memories ..., which finds the service whatever the container is called. A command using docker exec needs your chosen container name.

Do not use cpus: on a Synology​

DSM kernels without the CFS bandwidth controller reject a CPU quota with NanoCPUs can not be set. The shipped Compose file sets none. To leave a core for Immich, pin this app to three cores on a four-core NAS:

cpuset: "0-2"

title_screens.locale: auto follows the host's LANG, but the container sets none, so a film always renders in English until you set title_screens.locale: fr (or add LANG: fr_FR.UTF-8 to the environment: block) for a French one.

What to expect​

Basic films are capped at 1080p. The default 4 GiB memory limit suits that output. The first film takes the longest: it has to read every picture in its period before it can render. Larger periods, slower storage and different media can take hours. See measured examples for real numbers on comparable hardware.

The first film reads the pictures in its period and saves the results; later films reuse matching results. Rendering still happens every time.

Basic preparation leaves Marqo and Docling off; GPU/Full add those detectors, captions and the Laya pre-screen. Compatible facts already in the store stay banked when you change tiers. See what the upgrades add.

CPU titles draw their background and text once, then move, scale and fade the text with FFmpeg. The background stays still to keep software encoding cheap, and no extra package is needed. Titles and maps covers the title and map options.

Measured results records whole-film wall times and separate stage costs. Figures labelled preparation-only exclude downloads, music and rendering. A long film also gets a full playback check after rendering; the log reports its progress about once a minute.

Encoding​

An Intel NAS can use Quick Sync for H.264. Add the device block below to the app service in Compose (the shipped file has no device mapping by default), and use the numeric group that owns the render node:

stat -c '%g' /dev/dri/renderD128
devices:
- /dev/dri:/dev/dri
group_add:
- "937" # example DSM GID; use the number from stat

Verify with Hardware encoding. Passing the device without its group leaves it visible but unusable.

J4125-class NAS hardware cannot encode HEVC. With the default prefer_hardware policy, the app can choose H.264 instead. A strict H.265 or explicit HDR request can require software encoding. ARM64 Docker uses software encoding. Non-AVX Celerons use the simpler title renderer.

Memory and disk​

Allow about 25 GB plus 0.35 GB per 1,000 pictures and videos for persistent data, plus the image and finished films. Keep the persistent store. The preview cache grows with the pictures your films can reach, about 0.3 MB each, up to its 30 GB default; video clips and prepared sources take up to 10 GB each. Storage and caches covers caps and cleanup. Uploaded films are removed locally after confirmed delivery; local-only films keep growing.

Every night​

The running UI can make one memory a day. Enable the timer in Compose and set TZ: Docker automation. Automate it explains what it picks and how to upload the result.

Long films​

Stay at 1080p on NAS. For rendering on a stronger machine, use a render worker; that changes rendering, not the selection tier.

What a NAS can't do​

GPU selection needs the GPU services, and generated music needs an ACE-Step server on a GPU or Apple Silicon machine. A reader alone helps with the music mood, and names special days and trips when you turn on --llm-title (off by default). The add-on guide helps you choose the next piece.

Everything else​

The Docker instructions cover API-key permissions, uploads, backups and upgrades. Container commands need sudo only if your user isn't in the docker group.

Stop or remove this installation​

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