Unraid makes a good receiver. It is already on, already has a fixed address, and usually has far more disk for recordings than a cheap cloud box.
This page covers the thing that trips people up first - Unraid's Docker storage - and then the install itself. If your Docker is healthy, skip to Installing.
Everything below was checked against Unraid 6.12.13. UI labels are quoted exactly.
By default Unraid keeps every container inside one large file, docker.img, formatted btrfs and mounted through a loop device. When that file's filesystem is damaged it fails in a way that is easy to misread.
It looks like this in dmesg:
BTRFS error (device loop2): unable to find ref byte nr 298975232 parent 0 root 2077 owner 25114 BTRFS: Transaction aborted (error -2) BTRFS info (device loop2: state EA): forced readonly
What it means. The filesystem's record of which blocks are in use has lost an entry. Asked to free a block it has no reference for, btrfs cannot complete the transaction safely, so it does the responsible thing: it remounts itself read-only and stops making things worse. Unraid's own documentation notes the usual causes are the pool running out of space, or an unclean shutdown.
Why it misleads. Containers already running keep running, but nothing new can start and nothing can be written. So it presents as “most of my containers will not start” rather than “my storage is broken” - and the natural response, reinstalling the containers, appears to work, because rebooting remounts the image read-write.
It has not worked. A reboot clears the symptom, not the cause. The broken reference is still recorded inside the image. The next time Docker touches that block the filesystem aborts and goes read-only again - typically within minutes of boot. In the report that prompted this page it happened 220 seconds after startup.
Paste this into the Unraid terminal. It only reads; it changes nothing.
echo "== can Docker write right now?" touch /var/lib/docker/.wtest 2>/dev/null && echo " WRITABLE" && rm -f /var/lib/docker/.wtest || echo " READ-ONLY <-- the fault is still present" echo; echo "== filesystem identity (the uuid is what settles it)" btrfs fi show 2>/dev/null | grep -B1 loop echo; echo "== how Docker is storing data" docker info 2>/dev/null | grep -Ei 'docker root dir|storage driver|backing filesystem' echo; echo "== what your pool is formatted as (this decides your fix below)" for p in /mnt/*/; do case "$p" in /mnt/user*|/mnt/disk*|/mnt/rootshare*|/mnt/remotes*|/mnt/addons*) continue;; esac printf ' %-22s %s\n' "$p" "$(findmnt -n -o FSTYPE --target "$p" 2>/dev/null)" done echo; echo "== is the system share split onto the array?" for d in /mnt/disk*/system; do [ -e "$d" ] && echo " ALSO ON ARRAY: $d <-- a likely cause"; done echo; echo "== recent filesystem errors" dmesg | grep -iE 'btrfs.*(error|readonly|abort)' | tail -15
Reading it.
READ-ONLY - the fault is live right now.uuid line is what settles it. A filesystem keeps its uuid for life. If it is the same uuid that appeared in your original error, you are still on the same damaged image no matter how many containers you have reinstalled since. Only deleting and recreating produces a new uuid.ALSO ON ARRAY - the system share is not pinned to the pool. Fix that too, at step 3.
btrfs extent-tree damage is the one category btrfs's own developers tell you not to point btrfs check --repair at. Upstream lists --repair under DANGEROUS OPTIONS: “Do not use --repair unless you are advised to do so by a developer or an experienced user.” The extent-tree-specific --init-extent-tree carries its own “do not use unless you know what you're doing.” No Unraid documentation recommends repair either - the official procedure is to recreate.
There is also nothing in docker.img worth saving. It holds downloaded images and container layers, all re-downloadable. Your real data is elsewhere and is not affected:
/boot/config/plugins/dockerMan/templates-user, entirely outside the image.That is why containers come back configured after you recreate it.
About ten minutes, most of it re-downloading images.
Settings → Docker → Enable Docker: No → Apply.
The storage settings are not merely greyed out while Docker runs - Unraid does not render them at all. After you click Apply the page reloads and the extra fields appear. If you cannot see them, Docker has not stopped.
The advice forks here on what your pool is formatted as, from the diagnostic above.
Set Docker data-root to directory.
This is what stops the problem returning. The corruption you hit is a property of the loopback arrangement - a btrfs filesystem inside a single file inside another filesystem - not of Docker or of your disks. A directory removes that layer entirely. It also removes the fixed size, so Docker can no longer fill an image and wedge itself, and freed space returns to the pool instead of being stranded inside a file.
The Docker directory field pre-fills with /mnt/user/system/docker/docker/, which is fine. LimeTech's own recommended recipe is a dedicated share instead - a docker share pinned to the pool, with the directory set to /mnt/user/docker. Either works. Do step 3 regardless.
Set Docker data-root to xfs vDisk.
On Unraid 6.12, directory mode on a ZFS pool uses the zfs storage driver, which creates a dataset per image layer. LimeTech acknowledged in the Unraid 7.0 release notes that this “causes significant stability issues on ZFS volumes” and recommend switching to the overlay2 driver - which does not exist in 6.12. So on 6.12 that mitigation is not available to you, and directory mode on ZFS trades one storage problem for another.
xfs vDisk still uses an image file, but xfs has no extent tree of the kind that failed here, and it is the safe choice on 6.12 + ZFS.
Shares → system. On 6.12:
Primary storage (for new files and folders) → your pool (usually cache)Secondary storage → None
With Secondary set to None, Mover is disabled for the share and shows Not used. On pre-6.12 the equivalent is Use cache pool (for new files) = Only.
Do the same for appdata.
This matters more than it looks. If the share is allowed onto the array, Mover will eventually try to relocate files underneath a running Docker - and moving an open loopback image out from under a mounted filesystem is an effective way to produce exactly the damage you just had. Whether it caused yours is not knowable after the fact. Close it anyway.
With Docker stopped, tick Delete vDisk file. The Apply button relabels itself to Delete - that is the confirmation; there is no separate button.
(In directory mode the equivalent checkbox reads Delete directory. Right now you are deleting the old vDisk, so you want Delete vDisk file.)
If the checkbox is not shown, Unraid cannot see a file at the configured path. Remove it by hand instead:
rm -f /mnt/user/system/docker/docker.img
Settings → Docker → Enable Docker: Yes → Apply.
Then Apps → Previous Apps, tick what you want back, and install. That reads the templates from your flash drive, so containers return with their settings. The only cost is re-downloading the images.
After a few hours of normal use:
dmesg | grep -iE 'btrfs.*(error|readonly|abort)' | tail
Silence is the answer you want. On directory mode there will be no btrfs loop device left to complain at all.
Once Docker can write, the receiver is one command on the Unraid terminal:
wget -qO- https://streamhelpers.com/receiver | sh
It asks Docker to create a volume before downloading anything, so if the storage fault above is still present you get a clear sentence about it instead of a confusing failure part-way through a 69 MB download.
Unraid is x86-64 only, so the architecture check will never be a problem here.
Nothing, in the terminal. When it finishes it prints the address of the receiver's own settings page on port 8088. Open that page from your LAN and add a Tailscale auth key — the page has a box for it, marked required, and links to streamhelpers.com/tailscale-keys, which walks you through creating one. That key is how the dashboard reaches the receiver's controls without you opening a management port to the internet, and the pairing code you paste into the dashboard appears on the page the moment Tailscale connects. The full walkthrough is on Your own streaming server.
One port forwarded: udp/25554 - the bonded video arriving from the backpack.
It cannot travel through Tailscale. Bonding works by sending across several connections at once and continuously measuring which is healthiest; a tunnel collapses all of them onto one path, which defeats the whole mechanism while still looking like it works. So this port stays open even with Tailscale running. Nothing else needs forwarding - the control page rides the tailnet.
It will appear as an orphan container. Installing from the command line means there is no Unraid template behind it, so the Docker tab lists it without the usual icon and menu. It runs and restarts with the array — it just looks plain, and Unraid's own update button will not appear for it. Update it with the --reinstall command below instead.
Port 8088 is the settings page. If something already holds it, the installer names the container that has it rather than failing obscurely. The page only answers to addresses on your LAN or your tailnet; do not forward it.
/dev/net/tun and NET_ADMIN are requested for the receiver's built-in Tailscale. Unraid provides both; nothing to configure. You do not need Unraid's Tailscale plugin for the receiver, though you can still run it if you also want the Unraid host itself on your tailnet.
Storage. State lives in a Docker volume, streamhelpers-receiver-data — settings, Tailscale's node identity, and Restreamer's configuration and recordings. Recordings grow, so make sure the Docker storage you chose above has room for them; the volume lives inside it.
Tell the Appdata Backup plugin to skip it. If you run the Appdata Backup plugin from the Apps tab, it stops each container on its schedule, backs up its appdata folder and starts it again. This receiver keeps its state in the Docker volume above rather than in appdata, so the plugin finds nothing to save — its log says the container “does not have any volume to back up! Skipping” — but it has already stopped the receiver by then. A stream that is live at that moment drops everywhere at once: Restreamer restarts with the container, so every platform you publish to loses the feed, and the backpack's bonded connections have to register again before video can return. In the plugin's settings, tick Skip? next to StreamHelpers-Receiver in the per-container list; the plugin's own log suggests the same (“Please consider ignoring this container”). Found on a real server, whose weekly 03:00 Monday run reached the receiver at 03:41.
docker logs -f StreamHelpers-Receiver # watch what it is doing docker restart StreamHelpers-Receiver # restart it wget -qO- https://streamhelpers.com/receiver | sh -s -- --reinstall # update
--reinstall replaces the container and keeps the volume, so settings, Tailscale identity and recordings survive an update.
“Docker cannot create a volume” - the storage fault is still present. Go back to Fixing it properly. Nothing else will help, and reinstalling containers will not.
The settings page says the server cannot be paired yet, or Tailscale says the key was refused - auth keys expire and most are single-use. Generate a fresh one and paste it into the settings page; only the Tailscale service restarts, and no reinstall is needed.
The stream connects but nothing appears - almost always udp/25554 not reaching the server. Check the forward on your router and on any firewall in front of it. The dashboard's Bonding tab shows whether the receiver is answering, and the settings page's Status section shows each service's state and last log line.