TrueNAS

Use the Docker-based Apps system in TrueNAS 24.10 or newer. Older Kubernetes-based SCALE installs need a different deployment. These steps follow TrueNAS's custom app documentation; a recorded installation on TrueNAS is still pending.

Not yet tested on TrueNAS

We have not tested these steps on this platform. Local template, manifest and browser checks do not establish a tested installation. Please report your results, including platform/app versions and whether preflight and the first film worked. The deployment matrix tracks status by platform.

1. Open the YAML installer

With an Apps storage pool configured, open Apps → Discover → ⋮ → Install via YAML. Choose a lowercase application name such as immichmemories.

2. Paste and save

Enter your connection details below, paste the generated docker-compose.yml into Custom Config, and click Save. There is no adjacent .env file in this editor. If adapting a downloaded Compose file instead, resolve every ${...} expression before pasting, including image tags, paths and ports.

Setup files for docs build v1.0.0-rc.1. The app image and release assets use this same version.

Immich URLImmich API keyUI host portChoose a free port if another app already uses 8080. The UI stays localhost-only.

Create a key with the ten required read permissions. Add the five upload permissions only to send films back; asset.delete is optional. Avoid the All preset.

Choose a tier

BasicA complete film from metadata and small classifiers.GPUPicture descriptions, intent and extra sharing checks.FullA text reader refines the draft and writes titles.

Single file for a stack editorIncludes your credentials and a browser-generated settings key. Store the downloaded file privately.

Can I run this? Check the version and topology matrix.

Not yet tested as an end-to-end generated installation on Linux Docker Compose. Files are checked with Compose/Kustomize and the form is checked in a browser. Those checks do not run this installation. Earlier NAS, Mac and GPU Kubernetes checks are recorded in the measured results. Tried it? Report your platform, release and preflight result.

Your choices produce files in this browser. Nothing is sent to an Immich or model server.

Enter your Immich API key.

Keep Single file for a stack editor selected. Enter the Immich address your container can reach and its API key. The generated file includes a private Settings encryption key; keep the download with your backups. No .env file or hand-written YAML is needed.

The default Basic setup needs no separate model service. Set your home, people and optional service URLs in Settings. The config and output volumes keep settings, cached facts and films across container replacement. Download films through the app or enable upload-back. Include both volumes and the encryption key in your backups.

To keep films in a NAS share instead, replace the generated output volume mount with an absolute host path after creating that folder and giving UID/GID 1000 write access. See NAS folder permissions. That storage change is optional; the generated file works with its named volumes.

The example uses Docker-managed volumes. For datasets you can snapshot and share directly, create dedicated datasets first and replace the corresponding volume mounts with their absolute /mnt/... paths. Give UID/GID 1000 access to those datasets; do not change permissions on an entire existing storage pool.

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 as an environment variable) for a French one.

3. Prepare and check

Open Apps → Installed, select immichmemories, then in Workloads click the Shell icon for the running app container. Choose /bin/sh if prompted. This is the app shell, not System → Shell. Run:

immich-memories models fetch
immich-memories preflight

Do not add docker exec inside this shell. Fix reported connection or storage errors before making a film. No SSH is needed for preparation. The shell requires Web Shell Access and the apps write role (APPS_WRITE), or Full Admin; see TrueNAS's Workloads controls.

4. Open the app

With SSH enabled on TrueNAS, run this from your computer:

Use the Private UI access command generated above; it uses your selected UI port. Replace your-ssh-user@your-host with your NAS login and address.

Open the localhost URL shown by the builder and make your first film. For direct LAN access, enable authentication before changing the port binding. The TrueNAS admin login does not protect the app's port.