TrueNAS Apps: k3s to Docker Migration Guide

If you searched for how to do something with k3s on TrueNAS and landed here, the short answer is that there is nothing to do. No currently supported TrueNAS release runs Kubernetes. The k3s backend behind Apps was removed in TrueNAS SCALE 24.10 “Electric Eel” and replaced with Docker, and every release since has been Docker-based.

That single change invalidates a large body of TrueNAS documentation, blog posts and YouTube tutorials, most of which do not say which version they were written for. This is what changed, how to tell which side of the line a guide sits on, and what to do if you are still holding a system that never made the jump.

How to date a guide you are reading

Anything describing these things was written for 24.04 or earlier and does not apply to a current system:

• k3s, kubectl, helm, charts, or the k3s kubectl shell command
• The ix-applications dataset as the live location of app data
• NodePort ranges starting at 9000 and the “Node Port” setting on app forms
• The TrueCharts catalogue as an app source added through the UI

Anything describing these is current:

• Docker Compose YAML, services:, and the “Install via YAML” option
• The hidden .ix-apps dataset on the apps pool
• Host Path, ixVolume, SMB/CIFS Share and Tmpfs as storage types
• Per-app IP addressing

The version map makes the boundary clearer:

Release	Codename	Apps run on	Status
22.12	Bluefin	Kubernetes (k3s)	Archived
23.10	Cobia	Kubernetes (k3s)	Archived
24.04	Dragonfish	Kubernetes (k3s)	Archived
24.10	Electric Eel	Docker	Archived, final update August 2025
25.04	Fangtooth	Docker	Maintenance
25.10	Goldeye	Docker	Stable, recommended

TrueNAS 25.10 “Goldeye” is the release the status page recommends for general users, with 25.10.6 published on 12 August 2026. TrueNAS 26 is an early release, currently 26-BETA.2. Note that Electric Eel itself is archived now: it is the release that introduced Docker, not a release to settle on. There is no path back to a Kubernetes-based release that is still receiving fixes.

Why the backend changed

k3s is a lightweight Kubernetes distribution, but lightweight Kubernetes is still Kubernetes: a scheduler, a control plane, an ingress layer and a chart packaging format, all running on a single-node appliance that will never schedule a pod anywhere else. The abstraction bought nothing and cost a great deal, both in resident memory and in the number of layers between a user and a container that would not start.

Docker Compose is the format almost every self-hosted project publishes its deployment example in. Moving to it meant TrueNAS users could paste a project’s own published Compose file instead of waiting for someone to write a Helm chart for it. iXsystems described the 24.10 change as bringing industry-standard Docker Compose applications to TrueNAS so they benefit from ZFS underneath, which is a fair summary of what actually landed.

The memory effect is real but modest, and it is easy to overstate. The control plane overhead went away; the containers themselves cost what they always cost. Sizing an apps-heavy machine is still mostly a question of adding up what the apps ask for, on top of what ZFS wants for cache. That arithmetic is covered in TrueNAS hardware sizing, and the TrueNAS sizer on this site takes app count as one of its inputs for exactly this reason.

What migrated automatically, and what did not

Supported catalogue applications migrate to Docker deployments automatically on upgrade from 24.04 “Dragonfish” to Electric Eel. That covers the apps installed from the official TrueNAS catalogue: the container image, its configuration and its data land on the Docker side without manual work.

Applications from third-party catalogues do not migrate. TrueCharts was the largest of these, and its maintainers control their own timelines independently of TrueNAS releases, so those apps had to be backed up and redeployed by hand. Anyone who ran a TrueCharts-heavy stack and upgraded without preparing for that found the apps gone from the UI with their data still sitting on the pool.

The upgrade path itself has a wrinkle that catches people restoring old systems. The 24.10 release notes state that 24.10 and later do not support migrations from the 13.x CORE line, so a 13.x system of that era had to reach 24.04 first. That gap closed at 25.04: iXsystems published Fangtooth as the recommended and unified upgrade path for both 24.10 and CORE 13.x installations. What has not changed is the apps constraint: a Kubernetes-era apps system still has to pass through 24.04 to get its apps converted, because that is where the automated conversion lived.

The June 2025 deadline, and what it means for a stale system

There was a hard cutoff. An apps catalogue update that enabled per-app IP addressing broke backward compatibility with the Kubernetes-based app system, and iXsystems announced that after 1 June 2025 the automated apps migration would stop working on 23.10 “Cobia” and 24.04 “Dragonfish”. The guidance at the time was to upgrade to 24.10.2.2 before that date.

If you are reading this while sitting on a Cobia or Dragonfish system with Kubernetes apps still installed, the automated route is closed. What remains is a manual rebuild:

1. Take a configuration backup and a fresh snapshot of the apps dataset before touching anything.
2. For each app, record the image, tag, environment variables, port mappings and every host path it uses. The app’s edit screen in the old UI is the only reliable place these are all listed together.
3. Upgrade the system. Apps will not come across; the data on the pool will.
4. Reinstall each app from the current catalogue, or write a Compose file for it, and point it at the same host paths.
5. Start one app at a time and confirm it sees its old data before moving to the next.

Step two is the one people skip and regret. An app’s configuration is not recoverable from the container image; it lives in the deployment definition, and once the old backend is gone so is the definition.

Re-running a migration that failed

Where the automated migration ran but did not complete, it can be re-triggered after the upgrade. From a shell session on the system:

midclt call -job k8s_to_docker.migrate poolname

Replace poolname with the pool holding the apps, for example tank. This is documented as a way to re-initiate a failed migration of previously installed Kubernetes apps at any time after upgrading to Electric Eel.

The safety net behind it is that the old ix-applications dataset is retained as-is during migration rather than deleted, which is what preserves the ability to roll back to the previous Dragonfish installation. Docker app data goes to a new hidden dataset at /mnt/.ix-apps on the apps pool. Two consequences follow: the old dataset is still consuming space after a successful migration and can be removed deliberately once everything is confirmed working, and a rollback is only possible while it is still there.

What replaced the Kubernetes-era settings

The concepts did not disappear, they were renamed and simplified. Mapping the old vocabulary to the new one is most of what is needed to follow an old guide on a current system.

Kubernetes-era concept	Current equivalent
Helm chart from a catalogue	Catalogue app, or a Compose file via Install via YAML
Host Path Volume	Host Path storage type
ixVolume PVC	ixVolume storage type
NodePort in the 9000 range	Port mapping on the app, or host networking
Privileged pod security context	Explicit Linux capabilities, or privileged mode
k3s kubectl logs	The app’s Logs view, or docker logs from a shell

Two of these are worth understanding rather than just translating.

Storage type is a durability decision. Host Path mounts a dataset you created and can see, snapshot and replicate by name. ixVolume auto-creates a dataset inside the hidden apps area with a generated name. For anything whose data you would be upset to lose, Host Path on a dataset you named yourself is easier to back up and easier to find later. The dataset layout that makes this manageable is worth planning up front, alongside the rest of the pool and dataset design.

Host networking replaces the port juggling. Binding a container to the TrueNAS host network disables port mapping for that app, which is what services needing broadcast or multicast discovery on the LAN require. It also means the container’s ports land directly on the host’s addresses, so two apps wanting the same port will collide.

Installing something the catalogue does not carry

The Compose route is the reason the Docker move matters in practice. From Apps, open Discover, then the three-dot menu, then Install via YAML, which opens the Add Custom App screen. Give the app a lowercase alphanumeric name and paste the Compose content into Custom Config, starting at a top-level key such as name:, services: or include:.

Two cautions come straight from the documentation. TrueNAS performs only basic YAML syntax validation and does not validate the configuration parameters before running it, so a file that is structurally valid but wrong will fail at container start rather than at save time. And because YAML depends on indentation, writing the file in a real editor before pasting it in is the recommended workflow rather than typing it into a browser text box.

The include: key is the quietly useful one: it references an external Compose file on the system, which suits anyone who already maintains their Compose files as files and wants TrueNAS to run them rather than own them.

A worked example of this route, including host networking and device passthrough, is in the walkthrough for running a CUPS print server as a custom app.

Before you upgrade an apps-heavy system

• Export the system configuration and store it off the machine.
• Snapshot the apps dataset and any dataset an app writes to.
• List every app, its source catalogue, and every host path it touches.
• Identify anything from a third-party catalogue and plan to redeploy it by hand.
• Upgrade, then start apps one at a time rather than all at once.

None of this is difficult. All of it is much harder after the fact, because the record of how an app was configured lives in the backend that the upgrade replaces.