DoneCase file
Replacing TrueNAS with Debian 13 + Docker + Dockge (and keeping every setting)
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.
Why I did it
- 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
| Option | Trade-off |
|---|---|
| Tune TrueNAS SCALE in place | Claws back some RAM, but the appliance overhead stays. |
| Move the apps to the second Proxmox node | Fixes 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 Chosen | No appliance overhead, same ZFS, no pool rebuild. |
Pros and 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
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 upgradeorzpool createnear 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>Step 2: Install Debian 13 minimal, then ZFS
Same hardware, UEFI boot. Add the ZFS packages before going near the disks.
apt install zfsutils-linuxStep 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 listStep 4: Install Docker and Dockge
Point Dockge at the same compose directory structure the old setup used.
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.
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
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
dhcpcdrewrote/etc/resolv.confon 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 dhcpcdsu vs su -
- Symptom
- Admin commands came back "command not found" as root.
- Cause
sukeeps 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.confNextcloud 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/driaccess and its user was not in the host'srendergroup. - Fix
- Pass
/dev/drithrough 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 renderWatchtower jumped Jellyfin two major versions
- Symptom
- Jellyfin's web UI and branding changed overnight.
- Cause
- Watchtower tracked
:latestand 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
| Metric | Before | After |
|---|---|---|
| Free RAM at idle | Very little after appliance services | Most of it available to apps |
| Jellyfin playback | Stuttered roughly every 20s | Smooth |
| App reconfiguration | n/a | None, same compose files and pool |
| ZFS pool | Managed by TrueNAS | Same pool, imported, no rebuild |
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: 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
- ~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
.envfiles that are never committed, published, or included in backups that leave the box.
Lessons and 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.