Repository navigation
v1.6.0 — Fix Pi-hole boot failure + RAID5 streaming tuning
Fix: Pi-hole fails to start on every NAS reboot
Pi-hole binds to ${NAS_IP}:53 to avoid conflicting with the host's dnsmasq on 127.0.0.1:53. If NAS_IP is assigned via DHCP, Docker starts before the DHCP handshake completes — the port bind fails with exit 128, and Docker's restart policy does not retry start failures. This happens silently on every reboot, leaving your network without DNS.
What changed
- Compose: Removed Pi-hole from unnecessary
vpn-netnetwork (was causing a secondary race condition) - Compose: Expanded port binding comments explaining the dnsmasq conflict and static IP requirement
.env.example:NAS_IPnow documents the static IP requirement — what it means, how to check (ip addr show eth0), how to fix, and why a DHCP reservation isn't enough- SETUP.md: Static IP prerequisite callout in Pi-hole section with link to troubleshooting
- TROUBLESHOOTING.md: Full "Pi-hole doesn't start after reboot" guide — symptom, cause, diagnose commands, fix with copy-paste steps, and explanation of static IP vs DHCP reservation
Fix: Jellyfin 4K playback stuttering on RAID5
UGOS default RAID5 read-ahead (384 KB) is too small for streaming large files. A 4K remux at 67 Mbps causes the kernel to issue many small IO requests, each triggering a disk seek on spinning HDDs. Disk utilization hits 96%, the IO queue backs up, and playback freezes every 2-3 minutes.
What changed
- SETUP.md: RAID5 streaming tuning section in Jellyfin setup with commands to apply
- TROUBLESHOOTING.md: Full "Jellyfin video stutters/freezes" guide — symptom, cause, diagnose with
iostat, fix (read-ahead 4096 KB + stripe cache 4096 pages), and how to persist via/etc/rc.local
Result
| Metric | Before (384 KB) | After (4096 KB) |
|---|---|---|
| Disk utilization | ~96% | ~8-15% |
| Read latency | 20ms | 3-7ms |
| Queue depth | 26 | 0.07-0.16 |
Note: SSD caching does not help here — video playback is sequential read-once, so cached data is never re-read.
Upgrade notes
- If Pi-hole fails to start after rebooting your NAS, your
NAS_IPis likely from DHCP. See Troubleshooting: Pi-hole doesn't start after reboot for the fix. - If Jellyfin stutters on large files, see Troubleshooting: Jellyfin video stutters for the RAID5 tuning fix.
🤖 Generated with Claude Code