====== Running the receiver on Unraid ======
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|Installing]].
Everything below was checked against Unraid 6.12.13. UI labels are quoted exactly.
----
===== First: is your Docker storage actually healthy? =====
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.
==== Check whether you are still on the damaged image ====
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.
* **The ''%%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.
* **The pool filesystem type** decides which fix you want - see the fork at step 2.
* **''%%ALSO ON ARRAY%%''** - the ''%%system%%'' share is not pinned to the pool. Fix that too, at step 3.
==== Why not repair it? ====
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:
* **appdata** - configuration, databases - is a separate share.
* **Templates** live on the USB flash drive at ''%%/boot/config/plugins/dockerMan/templates-user%%'', entirely outside the image.
That is why containers come back configured after you recreate it.
----
===== Fixing it properly =====
About ten minutes, most of it re-downloading images.
==== Stop Docker ====
**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.
==== Choose your storage mode ====
The advice forks here on **what your pool is formatted as**, from the diagnostic above.
=== If your pool is btrfs or xfs -> use directory ===
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.
=== If your pool is ZFS -> use xfs vDisk instead ===
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.
==== Pin the system share to the pool ====
**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.
==== Delete the old image ====
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
==== Start Docker and reinstall ====
**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.
==== Confirm it is gone ====
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.
----
===== Installing =====
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.
==== What it asks for ====
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 [[https://streamhelpers.com/tailscale-keys|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 [[receiver:cloud-server|Your own streaming server]].
==== What it needs from your network ====
**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.
==== Notes specific to Unraid ====
**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.
==== Everyday commands ====
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.
----
===== If the install still fails =====
**"Docker cannot create a volume"** - the storage fault is still present. Go back to [[#fixing-it-properly|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.