TrueNAS SCALE Apps: Getting Started the Clean Way

Getting started with TrueNAS SCALE Apps comes down to two things: understanding that each app is a Docker container with storage you attach, and laying out that storage before you install anything. Do those two correctly and apps like Plex, Jellyfin, Nextcloud, Pi-hole, Vaultwarden, Home Assistant, and Immich are quick to stand up. Get the storage layout wrong and you create backup and migration pain that is annoying to undo later — so this guide front-loads the parts that matter.

The Apps system is one of TrueNAS SCALE’s biggest functional advantages over CORE: a built-in way to deploy containerized services directly on the NAS, with the storage already attached, without setting up a separate Docker ↗ host.

It is also, in equal measure, the system most likely to confuse a new SCALE user. The terminology overlaps with Docker and Kubernetes without being identical to either; the path to “I just want to run Jellyfin” is more layered than it looks; and a misconfigured app can write data into places you did not intend, which is awkward when those places are on the same pool as your photos.

This guide is a practical orientation.

How SCALE Apps actually work

Under the hood, TrueNAS SCALE Apps are containerized services. With SCALE 24.10 “Electric Eel”, iXsystems replaced the old Kubernetes-based system (k3s) with a native Docker engine, and Electric Eel also added support for standard Docker Compose apps. Catalog apps migrate automatically on upgrade from 24.04 (Dragonfish); third-party TrueCharts apps do not migrate automatically and need manual handling. Either way, you deploy and manage everything from the Apps section of the web UI.

What this means in practice:

• Each app runs in its own container, isolated from the host and from other apps.
• Each app has its own data volumes, which you point at datasets you create on your pool.
• Networking is bridged by default; you choose whether to expose an app port on the host’s network.
• Updates are pulled from container registries (Docker Hub, GitHub Container Registry) when you trigger an update.

You do not need to know Docker or Kubernetes to deploy stock apps from the catalog. You will benefit from knowing them if you eventually want to deploy custom containers via the Custom App option.

Set up the storage layout before installing anything

The single biggest mistake new SCALE users make: installing apps without thinking about where the app data goes.

Default app installs will offer to create their data directories under the app system’s managed pool path. This works, but co-mingles app config, app cache, and any media the app generates with internal SCALE app infrastructure. When you eventually want to back up just your Nextcloud data, separating it from a tangled ix-applications tree is painful.

Better pattern: create your own datasets for each app’s persistent data, then point the app at those datasets at install time. Datasets (not zvols) are the right choice here — they give you per-app snapshots, quotas, and tunable compression/recordsize.

tank/
├── apps/
│   ├── jellyfin/
│   │   ├── config/
│   │   └── cache/
│   ├── nextcloud/
│   │   ├── data/
│   │   ├── db/
│   │   └── config/
│   ├── immich/
│   │   ├── library/
│   │   ├── db/
│   │   └── thumbs/
│   └── homeassistant/
│       └── config/
└── media/      # already exists; apps mount this read-only or read-write
    ├── movies/
    ├── tv/
    └── photos/

Each app gets its own subtree under tank/apps/. Snapshot schedules can target the parent dataset tank/apps with one recursive task and reasonable retention.

A reference: deploying Jellyfin cleanly

Jellyfin is one of the simplest apps to deploy and the steps generalize. We use it as the worked example.

1. Prepare datasets

Create the app’s datasets via Datasets → Add Dataset:

• tank/apps/jellyfin
• tank/apps/jellyfin/config
• tank/apps/jellyfin/cache

Leave compression at lz4. Recordsize at 128K is fine.

2. Install the app

Go to Apps → Discover Apps, search for Jellyfin, click Install.

In the install wizard:

• Application Name: jellyfin (lowercase, hyphenated)
• Version: latest stable
• Network Configuration:
  • Web port: leave default (8096) or pick a custom port if 8096 is taken
  • Host Network: generally leave OFF unless you specifically need broadcast discovery
• Storage Configuration:
  • Jellyfin Config Storage: Use a host path → /mnt/tank/apps/jellyfin/config
  • Jellyfin Cache Storage: Use a host path → /mnt/tank/apps/jellyfin/cache
• Additional Storage / Volumes:
  • Add a mount: host path /mnt/tank/media/movies → container path /movies, read-only
  • Add a mount: host path /mnt/tank/media/tv → container path /tv, read-only

Mount your media read-only unless the app legitimately needs to write (Jellyfin does not — it reads media and writes metadata to its own config volume). Read-only mounts are a small but real safety boundary.

Save and wait for the app to come up. The first start can take 30–90 seconds while the image is pulled.

3. Configure inside the app

Hit the Web UI button on the app’s card to open Jellyfin. Walk through the initial setup wizard, pointing it at /movies and /tv as media libraries (the paths inside the container, not the host paths).

4. Set up reverse-proxy access if remote

For LAN-only access, you are done. For access from outside the LAN, set up a reverse proxy with HTTPS — either using the TrueNAS Apps catalog’s Traefik or Nginx Proxy Manager, or by running a proxy on a separate device. We recommend not exposing app ports directly to the public internet.

Apps that are worth running on the NAS

Some apps are obvious wins; others are better hosted elsewhere. A rough division:

Excellent fit for the NAS itself:

• Media servers: Plex, Jellyfin, Emby. The media lives on the NAS; serving it from the NAS avoids redundant network paths.
• Photo libraries: Immich, PhotoPrism. Photo libraries want fast access to large file collections — the NAS is exactly where you want them.
• File sync: Nextcloud, Syncthing. Same reasoning — data lives here.
• Backup targets: Borgbackup REST server, Restic REST server. The NAS is where backups land.

Better hosted elsewhere or in a VM:

• Home Assistant. Hardware integrations (USB Z-Wave/Zigbee adapters, GPIO devices) work poorly through container abstractions on TrueNAS. Either use the Home Assistant OS as a VM under SCALE, or run it on a dedicated Raspberry Pi or mini PC ↗.
• DNS resolvers (Pi-hole, AdGuard Home). Running your DNS resolver on a NAS means your house’s DNS depends on the NAS being up. Power-cycle the NAS for any reason and Internet feels broken until it returns. Dedicated tiny hardware is the better home for DNS.
• Network controllers (UniFi, Omada). Same reason — these are infrastructure services; depending on the NAS to keep your network managed is a worse coupling than running them on dedicated low-power hardware.
• Heavy compute (transcoding farms, ML). Add a GPU and a VM to TrueNAS if you want this on the NAS, but for most home users dedicated hardware is cleaner. If hardware transcoding for Plex/Jellyfin is the goal, plan it into your TrueNAS hardware build rather than retrofitting later.

Updating and snapshotting

Snapshot before every update. A periodic snapshot task on tank/apps with a daily cadence covers most accidental upgrades; before manually clicking “Update” on an app, take a one-off snapshot from the Datasets view of that app’s dataset. If the new image is broken or migrates data incompatibly, you can roll back the dataset.

Update apps one at a time, verify they work, then move on. Bulk-updating ten apps and discovering one is broken hours later is much harder to diagnose than updating one and testing it.

When apps misbehave

The most useful single command for diagnosing a broken app is the container log. From the Apps page, click the app’s name and then Logs in the menu that appears. 90% of “the app is broken” issues are visible there:

• Permission errors on a mounted volume → check the dataset ACL and the user the container runs as
• Database connection refused → the app’s internal database container did not come up, check its logs
• Image pull failures → the registry is down or the tag does not exist

For apps that come from non-official catalogs (TrueCharts, community catalogs), be prepared for occasional incompatibilities after TrueNAS version upgrades. Stock catalog apps tend to track TrueNAS more closely.

Where to go from here

• See Setting Up SMB Shares on TrueNAS SCALE for exposing your media datasets to non-app clients (Macs, Windows boxes, iPads).
• See TrueNAS Snapshot and Replication Strategy to set up a snapshot policy that protects your app data.
• See TrueNAS SCALE vs CORE in 2026 if you are still evaluating which platform to install.