DoneCase file

Replacing TrueNAS with Debian 13 + Docker + Dockge (and keeping every setting)

6 min read

Jellyfin was stuttering every 20 seconds and the NAS had almost no free RAM. The migration to a plain Debian 13 host, importing the ZFS pool without touching the data, and everything that went wrong: boot mode, DNS, a WireGuard kernel module, and Watchtower upgrading Jellyfin overnight.

  • Storage
  • Docker
  • Security
  • ZFS
NAS moves from TrueNAS to Debian with ZFS Left: TrueNAS with its RAM bar nearly full and playback stutter. Right: Debian with ZFS, RAM mostly free, and the same pool imported. TrueNAS RAM nearly full stutter ~20s Debian + ZFS RAM mostly free pool imported

Why I did it

4 reasons this had to change

  • The NAS ran TrueNAS SCALE on a 2-bay UGREEN DXP2800, with very little free RAM once the OS's own services were up.
  • Jellyfin stuttered roughly every 20 seconds during playback, a pattern that pointed at memory pressure, not the network or the disks.
  • This hardware is not getting more RAM, so the overhead had to come from somewhere else.
  • Goal: apps get the whole machine, with no re-setup of the *arr apps and no touching the media pool.

Options considered

3 options. Picked: Plain Debian 13 on the same hardware

OptionTrade-off
Tune TrueNAS SCALE in placeClaws back some RAM, but the appliance overhead stays.
Move the apps to the second Proxmox nodeFixes RAM on the NAS, but splits the apps from the disks they read constantly and adds network overhead.
Plain Debian 13 on the same hardware ChosenNo appliance overhead, same ZFS, no pool rebuild.

Pros and cons

4 pros, 3 cons

Pros

  • Most of the RAM goes to the apps
  • Same ZFS pool, imported instead of rebuilt
  • Same compose files, no app reconfiguration
  • Jellyfin playback is smooth again

Cons

  • No appliance UI: snapshot retention has to be set up by hand
  • Boot mode, DNS, VPN, and GPU access all needed fixes along the way
  • Monitoring for this host is not wired into Grafana yet

How it went

6 steps, start to finish

  1. Step 1: Back up configs, then export the pool

    Download the TrueNAS system config and copy every app's compose and config directory to external storage. Then export the pool. One rule for the whole migration: never run zpool upgrade or zpool create near the data disks.

    # TrueNAS UI: System Settings > General > Manage Configuration > Download
    # Copy each app's compose/config directory off the pool to external storage.
    
    # Confirm the pool name and health before exporting
    zpool status
    zpool list
    
    # Export cleanly. This detaches the pool and leaves the data untouched.
    zpool export <POOL_NAME>
  2. Step 2: Install Debian 13 minimal, then ZFS

    Same hardware, UEFI boot. Add the ZFS packages before going near the disks.

    apt install zfsutils-linux
  3. Step 3: Import the pool with an altroot

    Import under a controlled path, then symlink back to where the old compose files expect it. Zero compose edits.

    zpool import -o altroot=/mnt <POOL_NAME>
    ln -s /mnt/<POOL_NAME>/apps /opt/apps
    
    # Confirm every dataset came back
    zpool status
    zfs list
  4. Step 4: Install Docker and Dockge

    Point Dockge at the same compose directory structure the old setup used.

  5. Step 5: Bring each stack back from its saved compose file

    Jellyfin kept its libraries and watch history. The *arr apps kept their indexers and download clients. None of that data moved, only the OS underneath it.

  6. Step 6: Power-cycle test

    Rebooted the box and checked that the pool came back online, every container came back through Dockge, and the VPN container re-established its handshake with a non-home IP. No manual steps needed.

What went wrong

7 gotchas and how each was fixed

Install USB not detected

Symptom
The install USB was not offered as a boot device.
Cause
The box was set to Legacy boot with Secure Boot on.
Fix
Switch to UEFI boot mode and turn Secure Boot off for the install.

DNS overwritten mid-install

Symptom
Package installs started failing to resolve the Debian mirrors.
Cause
dhcpcd rewrote /etc/resolv.conf on every lease renewal, wiping a manual DNS entry.
Fix
Put the resolver in resolv.conf.head, which dhcpcd keeps as a prefix.
echo "nameserver <PIHOLE_IP>" | sudo tee /etc/resolv.conf.head
sudo systemctl restart dhcpcd

su vs su -

Symptom
Admin commands came back "command not found" as root.
Cause
su keeps the calling user's PATH, which on minimal Debian lacks /usr/sbin.
Fix
Use su - or sudo.

WireGuard kernel module

Symptom
The VPN container looked connected, but no traffic flowed.
Cause
The kernel module completed the handshake, then rejected the responses. Root cause not pinned down, so this is a workaround, not a diagnosis.
Fix
Block the kernel module so the container falls back to userspace WireGuard on the tun device.
# Egress IP should be the VPN's, not the home connection's
docker exec <VPN_CONTAINER> curl -s https://ifconfig.me

# Block the kernel module; the container falls back to userspace
echo "blacklist wireguard" | sudo tee /etc/modprobe.d/blacklist-wireguard.conf

Nextcloud volume mounted nothing

Symptom
After the migration, Nextcloud's NFS data volume came up empty.
Cause
Nextcloud runs on an app VM on Proxmox. Its Docker NFS volume had the old export path baked in.
Fix
Recreate the volume against the new NFSv4 export. A restart alone is not enough.

GPU transcoding fell back to CPU

Symptom
Playback worked, but CPU use jumped with no error.
Cause
The container had no /dev/dri access and its user was not in the host's render group.
Fix
Pass /dev/dri through and match the render group.
# In the Jellyfin compose file:
#   devices:
#     - /dev/dri:/dev/dri

# Check the render group's GID on the host
getent group render

Watchtower jumped Jellyfin two major versions

Symptom
Jellyfin's web UI and branding changed overnight.
Cause
Watchtower tracked :latest and pulled the 12.x line over 10.x. The Jellyfin Enhanced plugin also overrides the favicon from its own branding folder, which made the change look bigger.
Fix
Pin image tags on anything used daily. Updates become a decision, not a surprise.

Before and after

Side-by-side table and diagrams

MetricBeforeAfter
Free RAM at idleVery little after appliance servicesMost of it available to apps
Jellyfin playbackStuttered roughly every 20sSmooth
App reconfigurationn/aNone, same compose files and pool
ZFS poolManaged by TrueNASSame pool, imported, no rebuild
Before
Before: TrueNAS SCALE with RAM nearly full The NAS runs TrueNAS SCALE. Its RAM bar is almost full from appliance services, the apps are squeezed and stutter roughly every 20 seconds, and the ZFS pool sits underneath. NAS · TrueNAS SCALE UGREEN DXP2800 RAM very little free Apps Jellyfin + media stack stutter ~20s ZFS pool media + app data appliance services compete with the apps

Before: the NAS runs TrueNAS SCALE. Its RAM bar is almost full from appliance services, so the apps (Jellyfin and the media stack) are squeezed and playback stutters roughly every 20 seconds. The ZFS pool sits underneath.

After
After: Debian 13 with ZFS and Dockge, RAM mostly free The NAS runs Debian 13 with ZFS. Its RAM bar is mostly free. Docker managed by Dockge runs Jellyfin and the media stack. The same ZFS pool is imported, not touched, and an app VM running Nextcloud reads its data from the pool over NFSv4. NAS · Debian 13 + ZFS UGREEN DXP2800 RAM mostly free Docker + Dockge Jellyfin media stack ZFS pool imported, not touched NFSv4 app VM Nextcloud

After: the NAS runs Debian 13 with ZFS. Its RAM bar is mostly free. Docker managed by Dockge runs Jellyfin and the media stack. The same ZFS pool is imported, not touched, and an app VM running Nextcloud reads its data from the pool over NFSv4.

Results

Jellyfin stutter: ~20s → none

  • ~20s → noneJellyfin stutterWas roughly every 20 seconds
  • Mostly freeRAM after migrationWas: very little free
  • 0Apps reconfiguredSame compose files, same pool
  • 0Pool rebuildsExported, then imported

Security checks

  • VPN kill-switch verified: stopping the VPN container cuts the downloader's network access instead of falling back to the home connection.
  • No ports exposed to the internet from this box. Anything reachable from outside goes through the Cloudflare Tunnel.
  • The NFS export for Nextcloud is restricted to the one app VM that needs it, with root squash on.
  • Secrets live in .env files that are never committed, published, or included in backups that leave the box.

Lessons and what's next

5 lessons, then what's next

  • Export, don't destroy. The migration's safety rested on never running a destructive ZFS command near the data disks.
  • An altroot import plus a symlink meant zero compose edits. Plan the path layout before the migration.
  • Pin image tags on anything used daily.
  • Something that looks like a network problem is worth checking against memory and CPU first.
  • Test the full power-cycle path. A migration that works until the next reboot is not finished.

← Back to all projects