From Unraid XML Templates to Production Docker Compose: The Definitive Infrastructure-as-Code Blueprint

From Unraid XML Templates to Production Docker Compose: The Definitive Infrastructure-as-Code Blueprint

Executive Summary & Architectural Rationale

Unraid’s Docker implementation is famous for its ease of use. Through the Community Applications (CA) catalog, users can click an icon, fill out a web form, and launch a container within seconds. Behind the scenes, Unraid stores these container definitions as XML templates inside /boot/config/plugins/dockerMan/templates-user/. Whenever a container starts or updates, Unraid reads the XML and dynamically synthesizes an expansive docker run shell command.

For single, standalone containers, this model is undeniably convenient. But as a homelab scales into an interconnected production environment—spanning media streaming, automated acquisition pipelines, public-facing reverse proxies, centralized log aggregators, and relational database backends—the Unraid XML template model collapses under its own architectural constraints:

  1. Configuration Drift & Opaque State: XML templates are loosely coupled to running containers. Tweaking a parameter in the WebUI generates an ad-hoc docker run command with dozens of command-line flags. There is no Git version control, no PR review workflow, and no clean diffing mechanism.
  2. Absence of Multi-Container Orchestration: Real-world services rarely run in isolation. A Ghost publishing platform requires a tightly coupled MySQL 8 database; a BitTorrent client requires an uncompromising VPN tunnel with healthchecked killswitches; an automated subtitle downloader (bazarr) is useless until Sonarr and Radarr APIs are operational. Unraid templates treat every container as an island, with zero native dependency gating or shared life-cycle management.
  3. The Brittle Network Namespace Trap: Routing traffic from multiple containers through a WireGuard VPN container (like Gluetun) in standard Unraid requires brittle workarounds: injecting --net=container:gluetun into "Extra Parameters", manually declaring all forwarding ports on the Gluetun template, and praying that Gluetun boots before its client containers. If Gluetun crashes or restarts, its dependent containers are severed and fail silently.
  4. The FUSE shfs Performance & Lock Penalty: Community templates often encourage default path mappings such as /mnt/user/appdata/.... User shares route through Unraid’s userspace FUSE daemon (shfs), which introduces severe context-switching overhead and breaks POSIX file-locking semantics on SQLite databases (the storage engine powering Sonarr, Radarr, Prowlarr, and Plex).

To eliminate configuration drift, enforce strict startup dependency graphs (DAGs), secure our network boundaries, and bring true Infrastructure-as-Code (IaC) to our Unraid host, we migrated all 17 production containers into 4 consolidated Docker Compose stacks managed via the Unraid compose.manager plugin.

This blueprint details the architectural rationale, technical benefits, honest trade-offs, update workflows, disaster recovery integration, and the fully obfuscated production manifests powering our server.


The Master 4-Stack Architecture

Rather than maintaining a chaotic list of 17 independent containers, our services are partitioned into four cohesive domain stacks. Each stack lives in its own directory on the high-speed NVMe SSD cache at /mnt/cache/appdata/compose/<stack>/:

Unraid Master 4-Stack Production Architecture
Figure 1: Architectural topology of the 4 consolidated Compose stacks mapped against hardware resources, network namespaces, and multi-tier storage.

The Master Startup Dependency Graph (DAG)

In an unmanaged Unraid Docker environment, containers boot concurrently when the Docker daemon starts. This creates race conditions where client containers query uninitialized VPN tunnels, databases, or companion APIs. Under Docker Compose, each stack declares an explicit Directed Acyclic Graph (DAG) of dependencies:

Cold-Boot Startup Sequence & Dependency DAG
Figure 2: Complete startup dependency graph (DAG) across all 4 production stacks, enforcing healthchecked startup gating and inter-service prerequisites.

Architectural Deep Dive: The 4 Production Stacks

1. media-streaming (4 Containers)

  • Components: plex, jellyfin, tautulli, binhex-seerr
  • Network Mode: host for Plex and Jellyfin (mandatory for zero-overhead DLNA, GDM local subnet broadcast, and low-latency LAN playback); bridge for Tautulli and Seerr.
  • Hardware Acceleration: Full pass-through of the Intel Arc GPU via /dev/dri:/dev/dri to both Plex and Jellyfin. Intel QuickSync Video (QSV) transcode pipelines execute in hardware without container contention.
  • Startup Ordering: Tautulli and Overseerr declare depends_on: [ plex ]. They do not initialize until the media server is up, preventing socket connection errors during system boot.
  • Transcode Scratches: Mounted directly to RAM via /dev/shm:/transcode to eliminate NVMe SSD write wear during 4K video transcoding bursts.

2. arr-automation (7 Containers)

  • Components: gluetun, qbittorrent, prowlarr, bazarr, sonarr, radarr, houndarr
  • Coupled VPN Killswitch: qbittorrent, prowlarr, and bazarr join Gluetun's network namespace via network_mode: "service:gluetun". They have no independent virtual network adapters; their external traffic can only exit through Gluetun's WireGuard interface.
  • Inter-Service Gating: sonarr and radarr depend on qbittorrent and prowlarr. In turn, bazarr and houndarr depend on sonarr and radarr. This strict DAG eliminates startup race conditions where indexers or subtitle tools probe uninitialized APIs.

Healthcheck DAG Gating: Client containers declare:

depends_on:
  gluetun:
    condition: service_healthy

Gluetun only reports healthy after successfully handshaking with Private Internet Access (PIA) WireGuard servers and obtaining an active port forward. Containers cannot start in a naked, unencrypted network state.

3. infra-core (4 Containers)

  • Components: CloudflaredTunnel, duckdns, caddy, victorialogs
  • Edge Routing & Ingress: Cloudflare Zero Trust tunnel connects outbound to Cloudflare's global edge network, exposing selected private services without opening inbound firewall ports. DuckDNS maintains our dynamic IP pointer, while Caddy handles internal HTTPS certificates via Let's Encrypt DNS-01 challenges.
  • Centralized Observability: VictoriaLogs binds to UDP/TCP port 514, ingesting high-throughput syslog streams across all network switches, UniFi gateways, and Unraid host subsystems with 30-day retention.
  • Dependency: caddy declares depends_on: [ duckdns ] to guarantee dynamic DNS records are refreshed before ACME certificate handshakes execute.

4. blog (2 Containers)

  • Components: ghost-server, ghost-db (MySQL 8)

Database Readiness Guard: Ghost requires an active relational database at launch. If Ghost attempts to connect while MySQL is still running InnoDB replay logs, the Node.js process crashes and enters an unstable restart loop. We enforce deterministic boot via a custom MySQL healthcheck:

healthcheck:
  test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-p<MYSQL_ROOT_PASSWORD>"]
  interval: 30s
  timeout: 5s
  retries: 3
  start_period: 30s

ghost-server declares condition: service_healthy on ghost-db, guaranteeing seamless boots.


Preserving the Unraid WebUI Experience (The Magic Labels)

The number one objection homelabbers raise against moving to Docker Compose on Unraid is:

"If I switch to Docker Compose, I will lose my Unraid Docker dashboard icons, the clickable WebUI shortcuts, and my browser terminal buttons."

This is a common misconception. Unraid's Docker WebUI is fully compatible with containers created outside of its legacy XML templates, provided you supply the correct Docker container labels.

When migrating to Compose, you can define these labels directly in your docker-compose.yml or isolate them in a companion docker-compose.override.yml. The Unraid WebUI inspects every running container and renders GUI elements based on the following metadata:

Label Key Purpose & Format Example
net.unraid.docker.icon Absolute HTTPS URL to a transparent PNG/SVG logo rendered on the dashboard. https://raw.githubusercontent.com/linuxserver/docker-templates/master/linuxserver.io/img/sonarr-logo.png
net.unraid.docker.webui Browser endpoint URL for the container dropdown. Supports dynamic replacement tokens: [IP] (host IP) and [PORT:<num>]. http://[IP]:[PORT:8989]
net.unraid.docker.shell Determines whether the interactive WebUI console icon spawns bash or sh. bash (or sh for Alpine/distroless images)
net.unraid.docker.managed Informs Unraid’s template manager that this container is managed by the Compose plugin, disabling legacy template editing. composeman

The Unraid compose.manager plugin acts as a bridge. For each stack created, it places a tiny configuration block on the flash USB at /boot/config/plugins/compose.manager/projects/<stack>/:

  • name: The stack identifier (e.g., arr-automation).
  • indirect: An absolute pointer file containing the true path to your Compose directory on the NVMe cache (/mnt/cache/appdata/compose/arr-automation).
  • autostart: A boolean toggle (true/false) dictating whether Unraid launches the stack automatically when the Docker service starts.

Because the YAML files reside on /mnt/cache/appdata/compose/, editing them does not incur write wear on the Unraid boot flash drive. Furthermore, changes made in VS Code or via Git immediately reflect in the Unraid GUI.


Architectural Wins & Hard Engineering Problems Solved

1. Eliminating the FUSE shfs SQLite Lock Contention

In standard Unraid setups, containers frequently map volumes using paths like /mnt/user/appdata/radarr. The /mnt/user/ virtual mount is handled by shfs, a custom userspace FUSE filesystem. While FUSE is great for pooling heterogeneous spinning disks, it introduces substantial latency:

  • Every filesystem operation incurs multiple kernel-to-userspace context switches.
  • POSIX file-locking primitives are emulated, often failing under rapid multi-threaded read/write bursts.

For applications powered by SQLite databases (Sonarr, Radarr, Prowlarr, Plex, Bazarr), FUSE causes intermittent database lock errors (database is locked / disk I/O error) and UI freezes during large library refreshes.

By migrating to Docker Compose, we standardized all appdata volume binds directly to the NVMe filesystem:

volumes:
  - /mnt/cache/appdata/radarr:/config

This completely bypasses shfs. SQLite accesses the underlying XFS filesystem directly, cutting I/O latency to raw NVMe performance levels (~0.05 ms) and permanently ending database lockups.

2. Coupled VPN Killswitch & Port Forwarding

In our automated acquisition stack, leak prevention is non-negotiable. If qBittorrent downloads a torrent outside the VPN, or if Prowlarr scrapes indexers using our public residential IP, privacy is compromised.

Under legacy Unraid templates, achieving a true killswitch required manual network hacks and offered zero boot synchronization. Under Docker Compose, network coupling is bulletproof:

Client containers bind directly to Gluetun:

network_mode: "service:gluetun"
depends_on:
  gluetun:
    condition: service_healthy

gluetun serves as the network gateway, publishing the required WebUI and BitTorrent listen ports:

ports:
  - "8085:8085"       # qBittorrent WebUI
  - "6881:6881"       # Peer TCP
  - "6881:6881/udp"   # Peer UDP
  - "9696:9696"       # Prowlarr WebUI
  - "6767:6767"       # Bazarr WebUI

If the Gluetun container halts, the network interface disappears. The client containers cannot send a single packet to the outside world. Furthermore, Docker Compose ensures that if Gluetun is restarted, its dependent containers are gracefully restarted alongside it.

3. Hardware Transcoding (Intel QuickSync / Arc GPU)

Under Intel Core Ultra (Meteor Lake) and recent Core architectures, hardware acceleration utilizes the /dev/dri render nodes (renderD128). In Compose, passing this compute node to multiple streaming services is trivial:

devices:
  - /dev/dri:/dev/dri

Both Plex and Jellyfin access the Intel Arc graphics engine concurrently. While Plex serves primary household clients, Jellyfin operates as a backup server, with both sharing the exact same hardware transcoding capabilities without driver contention.

4. Deterministic Startup DAGs: Eliminating Timing & Race Conditions

A critical architectural consideration in multi-container homelabs is timing dependencies: Should automation tools like Sonarr and Radarr wait for media servers like Plex or Jellyfin before booting?

The answer is no:

  • Storage Independence: Sonarr and Radarr do not write to Plex; they write directly to persistent network storage (/mnt/user/tv and /mnt/user/movies). Plex reads from these shares passively or updates via webhook notifications. If Plex is temporarily offline during a media import, files are still placed cleanly on disk without error.
  • Critical Pipeline Dependencies: Conversely, internal pipeline prerequisites are non-negotiable:
    • gluetun (WireGuard) must complete its handshake and healthcheck before qbittorrent and prowlarr start. Otherwise, their outbound requests fail or risk leaking through an unprotected interface.
    • qbittorrent & prowlarr must be listening before sonarr and radarr initialize, ensuring download client tests and indexer synchronization succeed on first boot.
    • sonarr & radarr must be accessible before bazarr (subtitles) and houndarr (library health scanner) launch, preventing connection timeouts and API error storms.
    • duckdns must register the dynamic host IP before caddy initiates ACME certificate validation handshakes.
    • ghost-db must be healthy (MySQL accepting queries) before ghost-server connects, eliminating Node.js boot crash loops.

By structuring these relationships via depends_on and Docker healthchecks, the entire server boots deterministically from cold storage with zero manual intervention.


Honest Trade-offs & Cons: What You Lose

Engineering is about trade-offs. While Docker Compose brings massive stability and DevOps rigor, there are real drawbacks compared to Unraid's default template ecosystem:

1. Loss of Unraid CA "One-Click Update" Buttons

In Unraid's default Docker dashboard, each container displays an "update ready" indicator when a new image tag appears on Docker Hub/GHCR, allowing you to update individual containers with a single click.

  • The Reality: For Compose-managed containers, Unraid’s WebUI suppresses or cannot safely execute this one-click update, because doing so would trigger Unraid's legacy docker run engine and overwrite your Compose network topology.
  • The Mitigation: Container updates must be performed at the stack level—either via the Compose Manager WebUI ("Update Stack") or via a single CLI command (docker compose pull && docker compose up -d).

2. Manual Icon & WebUI Curation

In Community Applications, template authors pre-configure icons, web interfaces, and help links. When authoring Compose YAMLs from scratch, you must manually hunt down logo URLs and specify WebUI port tokens ([IP]:[PORT:xxxx]). If you omit the net.unraid.docker.* labels, your containers will appear on the Unraid dashboard with generic grey question marks and no clickable links.

3. The Dual-Autostart Collision Trap

This is the single most dangerous pitfall when migrating an existing Unraid host to Compose.
Unraid maintains its own internal autostart list at /var/lib/docker/unraid-autostart. If you import existing containers into Docker Compose but leave their legacy XML templates configured with Autostart = ON, both Unraid's core daemon and Compose Manager will attempt to start the containers simultaneously upon boot.

  • The Symptom: Random port collision errors (Bind for 0.0.0.0:8085 failed: port is already allocated), orphaned container instances, and broken network bindings.
  • The Fix: You must explicitly delete the old XML templates from /boot/config/plugins/dockerMan/templates-user/ and ensure legacy containers are fully removed from docker ps -a before handing management over to Compose.

4. Port Visibility Abstraction in Gluetun

Because qbittorrent, prowlarr, and bazarr use network_mode: "service:gluetun", they do not own independent IP or port namespaces. Their port forwards must be declared on the gluetun service block. For newcomers inspecting the YAML, seeing port 8085 (qBittorrent) defined under Gluetun rather than under qBittorrent can be initially counterintuitive.


Update Strategy, Lifecycle & Disaster Recovery

1. The Production Update Workflow

Never update containers blindly in a production environment. With Compose, updates are predictable and atomic.

Method A: The WebUI Route (Compose Manager)

  1. Navigate to Docker -> Docker Compose in the Unraid WebUI.
  2. Next to the target stack (e.g., media-streaming), click the Gear Icon -> Pull.
  3. Once the new layers download, click Down, followed by Up. The stack restarts cleanly with zero configuration drift.

Method B: The Terminal Route (DevOps CLI)

For engineers who prefer the shell, updates take three commands:

# Navigate to stack directory
cd /mnt/cache/appdata/compose/arr-automation

# Pull latest upstream images
docker compose pull

# Recreate changed containers with zero downtime for unchanged services
docker compose up -d

# Prune dangling images to free SSD cache space
docker image prune -f

2. Disaster Recovery: Integrating with appdata.backup

A common vulnerability in custom Compose setups is forgetting to back up the YAML manifests. If your NVMe SSD dies or the cache pool corrupts, you might restore your container configs from backup only to realize your Compose definitions were lost.

To solve this, we integrated our Compose directories directly into Unraid's official backup utility (Appdata Backup / ca.backup2).

In /boot/config/plugins/appdata.backup/config.json, we configured the includeFiles directive to monitor the Compose directory tree:

{
  "includeFiles": [
    "/mnt/cache/appdata/compose"
  ]
}

How the Backup Executes:

  1. Every Sunday morning at 03:00, appdata.backup stops running containers cleanly.
  2. It backs up all /config databases into compressed .tar.zst archives.
  3. It bundles /mnt/cache/appdata/compose/ into extra_files.tar.zst.
  4. It restarts all stacks according to their defined startup DAGs.

Full Bare-Metal Recovery:

If our server experienced total drive failure today:

  1. Boot Unraid and format a replacement NVMe cache pool.
  2. Restore the latest backup via appdata.backup.

Run a one-line recovery script:

for stack in infra-core media-streaming blog arr-automation; do
  docker compose -f /mnt/cache/appdata/compose/$stack/docker-compose.yml up -d
done

Within 90 seconds, all 17 containers, their network killswitches, their icons, and their WebUI links are 100% operational.

3. Image Tag Pinning & Rollback Playbook

For mission-critical services like databases and our public CMS, we avoid :latest tags:

  • ghost-db is pinned strictly to mysql:8 (preventing unwanted major upgrades to MySQL 9).
  • If an upstream container update introduces a bug (e.g., a Plex transcoder regression), rolling back takes seconds:
    1. Execute docker compose up -d. Compose recreates only the downgraded container.

Edit docker-compose.yml to specify the previous known-good tag:

image: ghcr.io/linuxserver/plex:1.41.0.8992-80f2a231b-ls245

Production Manifests (Sanitized & Obfuscated)

[!IMPORTANT]
All sensitive tokens, Private Internet Access credentials, MySQL passwords, DuckDNS tokens, and Cloudflare tunnel keys have been replaced with descriptive <OBFUSCATED> placeholders. Replace these placeholders with your own secrets before deploying.

1. Global Environment File (/mnt/cache/appdata/compose/.env)

All stacks share common environment variables stored in a central .env file:

PUID=99
PGID=100
UMASK=022
TZ=America/Toronto
HOST_IP=10.10.1.2
APPDATA_PATH=/mnt/cache/appdata
DOWNLOADS_PATH=/mnt/cache/downloads
TV_PATH=/mnt/user/tv
MOVIES_PATH=/mnt/user/movies

2. Media Streaming Stack (media-streaming/docker-compose.yml)

services:
  plex:
    image: ghcr.io/linuxserver/plex:latest
    container_name: plex
    network_mode: host
    restart: unless-stopped
    devices:
      - /dev/dri:/dev/dri
    environment:
      - PUID=${PUID}
      - PGID=${PGID}
      - TZ=${TZ}
      - VERSION=latest
      - UMASK=${UMASK}
    volumes:
      - ${APPDATA_PATH}/plex:/config
      - ${TV_PATH}:/tv
      - ${MOVIES_PATH}:/movies
      - /dev/shm:/transcode
    labels:
      net.unraid.docker.icon: "https://raw.githubusercontent.com/linuxserver/docker-templates/master/linuxserver.io/img/plex-logo.png"
      net.unraid.docker.webui: "http://[IP]:[PORT:32400]/web"
      net.unraid.docker.shell: "bash"
      net.unraid.docker.managed: "composeman"

  jellyfin:
    image: ghcr.io/linuxserver/jellyfin:latest
    container_name: jellyfin
    network_mode: host
    restart: unless-stopped
    devices:
      - /dev/dri:/dev/dri
    environment:
      - PUID=${PUID}
      - PGID=${PGID}
      - TZ=${TZ}
      - UMASK=${UMASK}
      - JELLYFIN_PublishedServerUrl=http://${HOST_IP}
    volumes:
      - ${APPDATA_PATH}/jellyfin:/config
      - ${TV_PATH}:/data/tvshows
      - ${MOVIES_PATH}:/data/movies
      - /dev/shm:/transcode
    labels:
      net.unraid.docker.icon: "https://raw.githubusercontent.com/linuxserver/docker-templates/master/linuxserver.io/img/jellyfin-logo.png"
      net.unraid.docker.webui: "http://[IP]:[PORT:8096]"
      net.unraid.docker.shell: "bash"
      net.unraid.docker.managed: "composeman"

  tautulli:
    image: ghcr.io/linuxserver/tautulli:latest
    container_name: tautulli
    restart: unless-stopped
    depends_on:
      - plex
    ports:
      - "8181:8181"
    environment:
      - PUID=${PUID}
      - PGID=${PGID}
      - TZ=${TZ}
      - UMASK=${UMASK}
    volumes:
      - ${APPDATA_PATH}/tautulli:/config
    labels:
      net.unraid.docker.icon: "https://raw.githubusercontent.com/linuxserver/docker-templates/master/linuxserver.io/img/tautulli-logo.png"
      net.unraid.docker.webui: "http://[IP]:[PORT:8181]"
      net.unraid.docker.shell: "bash"
      net.unraid.docker.managed: "composeman"

  binhex-seerr:
    image: ghcr.io/seerr-team/seerr:latest
    container_name: binhex-seerr
    restart: unless-stopped
    depends_on:
      - plex
    user: "${PUID}:${PGID}"
    ports:
      - "5055:5055"
    environment:
      - TZ=${TZ}
    volumes:
      - ${APPDATA_PATH}/binhex-seerr/seerr:/app/config
    labels:
      net.unraid.docker.icon: "https://raw.githubusercontent.com/binhex/templates/main/unraid/binhex/images/seerr-icon.png"
      net.unraid.docker.webui: "http://[IP]:[PORT:5055]"
      net.unraid.docker.shell: "sh"
      net.unraid.docker.managed: "composeman"

3. Automated Acquisition Stack (arr-automation/docker-compose.yml)

services:
  gluetun:
    image: ghcr.io/qdm12/gluetun:latest
    container_name: gluetun
    restart: unless-stopped
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun:/dev/net/tun
    ports:
      - "8085:8085"       # qBittorrent WebUI
      - "6881:6881"       # BitTorrent peer TCP
      - "6881:6881/udp"   # BitTorrent peer UDP
      - "8888:8888"       # HTTP Proxy
      - "9696:9696"       # Prowlarr WebUI
      - "6767:6767"       # Bazarr WebUI
    volumes:
      - ${APPDATA_PATH}/gluetun:/gluetun
    environment:
      - VPN_SERVICE_PROVIDER=custom
      - VPN_TYPE=wireguard
      - OPENVPN_USER=<PIA_VPN_USERNAME>
      - OPENVPN_PASSWORD=<PIA_VPN_PASSWORD>
      - OPENVPN_CUSTOM_CONFIG=/gluetun/custom.ovpn
      - VPN_PORT_FORWARDING=on
      - VPN_PORT_FORWARDING_PROVIDER=private internet access
      - VPN_PORT_FORWARDING_USERNAME=<PIA_VPN_USERNAME>
      - VPN_PORT_FORWARDING_PASSWORD=<PIA_VPN_PASSWORD>
      - SERVER_NAME=montreal436
      - FIREWALL_OUTBOUND_SUBNETS=10.10.1.0/24
      - TZ=${TZ}
    labels:
      net.unraid.docker.icon: "https://raw.githubusercontent.com/qdm12/gluetun/master/doc/logo_256.png"
      net.unraid.docker.shell: "sh"
      net.unraid.docker.managed: "composeman"

  qbittorrent:
    image: ghcr.io/linuxserver/qbittorrent:latest
    container_name: qbittorrent
    restart: unless-stopped
    network_mode: "service:gluetun"
    depends_on:
      gluetun:
        condition: service_healthy
    environment:
      - PUID=${PUID}
      - PGID=${PGID}
      - TZ=${TZ}
      - WEBUI_PORT=8085
    volumes:
      - ${APPDATA_PATH}/qbittorrent:/config
      - ${DOWNLOADS_PATH}:/downloads
      - ${DOWNLOADS_PATH}:/data
    labels:
      net.unraid.docker.icon: "https://raw.githubusercontent.com/linuxserver/docker-templates/master/linuxserver.io/img/qbittorrent-logo.png"
      net.unraid.docker.webui: "http://10.10.1.2:8085/"
      net.unraid.docker.shell: "bash"
      net.unraid.docker.managed: "composeman"

  prowlarr:
    image: ghcr.io/linuxserver/prowlarr:latest
    container_name: prowlarr
    restart: unless-stopped
    network_mode: "service:gluetun"
    depends_on:
      gluetun:
        condition: service_healthy
    environment:
      - PUID=${PUID}
      - PGID=${PGID}
      - TZ=${TZ}
      - UMASK=${UMASK}
    volumes:
      - ${APPDATA_PATH}/prowlarr:/config
    labels:
      net.unraid.docker.icon: "https://raw.githubusercontent.com/linuxserver/docker-templates/master/linuxserver.io/img/prowlarr-logo.png"
      net.unraid.docker.webui: "http://[IP]:[PORT:9696]/system/status"
      net.unraid.docker.shell: "bash"
      net.unraid.docker.managed: "composeman"

  sonarr:
    image: ghcr.io/linuxserver/sonarr:latest
    container_name: sonarr
    restart: unless-stopped
    depends_on:
      gluetun:
        condition: service_healthy
      qbittorrent:
        condition: service_started
      prowlarr:
        condition: service_started
    ports:
      - "8989:8989"
    environment:
      - PUID=${PUID}
      - PGID=${PGID}
      - TZ=${TZ}
      - UMASK=${UMASK}
    volumes:
      - ${APPDATA_PATH}/sonarr:/config
      - ${TV_PATH}:/tv
      - ${DOWNLOADS_PATH}:/downloads
    labels:
      net.unraid.docker.icon: "https://raw.githubusercontent.com/linuxserver/docker-templates/master/linuxserver.io/img/sonarr-logo.png"
      net.unraid.docker.webui: "http://[IP]:[PORT:8989]"
      net.unraid.docker.shell: "bash"
      net.unraid.docker.managed: "composeman"

  radarr:
    image: ghcr.io/linuxserver/radarr:latest
    container_name: radarr
    restart: unless-stopped
    depends_on:
      gluetun:
        condition: service_healthy
      qbittorrent:
        condition: service_started
      prowlarr:
        condition: service_started
    ports:
      - "7878:7878"
    environment:
      - PUID=${PUID}
      - PGID=${PGID}
      - TZ=${TZ}
      - UMASK=${UMASK}
    volumes:
      - ${APPDATA_PATH}/radarr:/config
      - ${MOVIES_PATH}:/movies
      - ${DOWNLOADS_PATH}:/downloads
    labels:
      net.unraid.docker.icon: "https://raw.githubusercontent.com/linuxserver/docker-templates/master/linuxserver.io/img/radarr-logo.png"
      net.unraid.docker.webui: "http://[IP]:[PORT:7878]"
      net.unraid.docker.shell: "bash"
      net.unraid.docker.managed: "composeman"

  bazarr:
    image: ghcr.io/linuxserver/bazarr:latest
    container_name: bazarr
    restart: unless-stopped
    network_mode: "service:gluetun"
    depends_on:
      gluetun:
        condition: service_healthy
      sonarr:
        condition: service_started
      radarr:
        condition: service_started
    environment:
      - PUID=${PUID}
      - PGID=${PGID}
      - TZ=${TZ}
      - UMASK=${UMASK}
    volumes:
      - ${APPDATA_PATH}/bazarr:/config
      - ${TV_PATH}:/tv
      - ${MOVIES_PATH}:/movies
    labels:
      net.unraid.docker.icon: "https://raw.githubusercontent.com/linuxserver/docker-templates/master/linuxserver.io/img/bazarr-logo.png"
      net.unraid.docker.webui: "http://[IP]:[PORT:6767]"
      net.unraid.docker.shell: "bash"
      net.unraid.docker.managed: "composeman"

  houndarr:
    image: ghcr.io/av1155/houndarr:latest
    container_name: houndarr
    restart: unless-stopped
    depends_on:
      - sonarr
      - radarr
    ports:
      - "8877:8877"
    environment:
      - PUID=${PUID}
      - PGID=${PGID}
      - TZ=${TZ}
      - HOUNDARR_AUTH_MODE=builtin
      - HOUNDARR_LOG_RETENTION_DAYS=30
    volumes:
      - ${APPDATA_PATH}/houndarr:/data
    labels:
      net.unraid.docker.icon: "https://raw.githubusercontent.com/av1155/houndarr/main/src/houndarr/static/img/houndarr-logo-dark.png"
      net.unraid.docker.webui: "http://[IP]:[PORT:8877]"
      net.unraid.docker.shell: "bash"
      net.unraid.docker.managed: "composeman"

4. Core Infrastructure Stack (infra-core/docker-compose.yml)

services:
  CloudflaredTunnel:
    image: cloudflare/cloudflared:latest
    container_name: CloudflaredTunnel
    restart: unless-stopped
    command: tunnel --no-autoupdate run --token <CLOUDFLARE_TUNNEL_TOKEN>
    labels:
      net.unraid.docker.icon: "https://github.com/Joey291/unraid-templates/raw/main/templates/cloudflare-icon.png"
      net.unraid.docker.shell: "sh"
      net.unraid.docker.managed: "composeman"

  duckdns:
    image: ghcr.io/linuxserver/duckdns:latest
    container_name: duckdns
    restart: unless-stopped
    environment:
      - PUID=${PUID}
      - PGID=${PGID}
      - TZ=${TZ}
      - SUBDOMAINS=<YOUR_SUBDOMAIN>.duckdns.org
      - TOKEN=<DUCKDNS_API_TOKEN>
      - UPDATE_IP=ipv4
      - LOG_FILE=false
    volumes:
      - ${APPDATA_PATH}/duckdns:/config
    labels:
      net.unraid.docker.icon: "https://raw.githubusercontent.com/linuxserver/docker-templates/master/linuxserver.io/img/duckdns-logo.png"
      net.unraid.docker.shell: "bash"
      net.unraid.docker.managed: "composeman"

  caddy:
    image: serfriz/caddy-duckdns:latest
    container_name: caddy
    restart: unless-stopped
    depends_on:
      - duckdns
    ports:
      - "8080:80"
      - "8443:443"
    environment:
      - DUCKDNS_API_TOKEN=<DUCKDNS_API_TOKEN>
    volumes:
      - ${APPDATA_PATH}/caddy/Caddyfile:/etc/caddy/Caddyfile:ro
      - ${APPDATA_PATH}/caddy/data:/data
      - ${APPDATA_PATH}/caddy/config:/config
    healthcheck:
      test: ["CMD-SHELL", "curl -s -f http://localhost:2019/config/ > /dev/null || exit 1"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 15s
    labels:
      net.unraid.docker.icon: "https://raw.githubusercontent.com/walkxcode/dashboard-icons/main/png/caddy.png"
      net.unraid.docker.shell: "sh"
      net.unraid.docker.managed: "composeman"

  victorialogs:
    image: victoriametrics/victoria-logs:latest
    container_name: victorialogs
    restart: unless-stopped
    command:
      - -storageDataPath=/vlogs-data
      - -syslog.listenAddr.udp=:514
      - -syslog.listenAddr.tcp=:514
      - -syslog.useRemoteIP.udp=true
      - -syslog.useRemoteIP.tcp=true
      - -retentionPeriod=30d
    ports:
      - "9428:9428"
      - "514:514"
      - "514:514/udp"
    volumes:
      - ${APPDATA_PATH}/victorialogs:/vlogs-data
    labels:
      net.unraid.docker.icon: "https://raw.githubusercontent.com/walkxcode/dashboard-icons/main/png/victoriametrics.png"
      net.unraid.docker.webui: "http://[IP]:[PORT:9428]/select/vmui/"
      net.unraid.docker.shell: "sh"
      net.unraid.docker.managed: "composeman"

5. Ghost CMS & Database Stack (blog/docker-compose.yml)

services:
  ghost-db:
    image: 'mysql:8'
    container_name: ghost-db
    restart: always
    command: '--mysql-native-password=ON --innodb-buffer-pool-size=536870912 --innodb-flush-log-at-trx-commit=2'
    environment:
      MYSQL_ROOT_PASSWORD: <MYSQL_ROOT_PASSWORD>
    volumes:
      - '${APPDATA_PATH}/ghost/mysql:/var/lib/mysql'
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-p<MYSQL_ROOT_PASSWORD>"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 30s

  ghost-server:
    image: 'ghost:latest'
    container_name: ghost-server
    cap_add:
      - CAP_SYS_NICE
    restart: always
    ports:
      - '2368:2368'
    depends_on:
      ghost-db:
        condition: service_healthy
    environment:
      url: 'https://fahim.ca'
      database__client: mysql
      database__connection__host: ghost-db
      database__connection__user: root
      database__connection__password: <MYSQL_ROOT_PASSWORD>
      database__connection__database: ghost_prod
      security__staffDeviceVerification: false
    volumes:
      - '${APPDATA_PATH}/ghost/content:/var/lib/ghost/content'
    healthcheck:
      test: ["CMD", "node", "-e", "const http=require('http');const opts={host:'127.0.0.1',port:2368,path:'/ghost/api/v4/admin/site/',headers:{'X-Forwarded-Proto':'https'}};http.get(opts,r=>process.exit(r.statusCode===200?0:1)).on('error',()=>process.exit(1));"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 30s

The Migration Checklist: Step-by-Step

If you are planning to migrate your Unraid server from legacy templates to Docker Compose, follow this battle-tested execution sequence to avoid downtime, IP collisions, and orphaned templates:

  • [x] Step 1: Install Compose Manager: Install compose.manager from Unraid Community Applications.
  • [x] Step 2: Create Directory Hierarchy: Establish /mnt/cache/appdata/compose/ with subdirectories for each intended domain stack.
  • [x] Step 3: Export Global Environment Variables: Create .env in /mnt/cache/appdata/compose/ declaring PUID, PGID, APPDATA_PATH, and timezone.
  • [x] Step 4: Author Compose Manifests & Labels: Define your service blocks, volume mappings, and Unraid GUI labels (net.unraid.docker.icon, webui, shell, managed: composeman).
  • [x] Step 5: Capture Existing Container State: Run docker inspect <container> on existing services to verify all active port forwardings, environment variables, and mount points.
  • [x] Step 6: Stop & Remove Legacy Containers: Stop the legacy containers in the Unraid GUI and remove them (docker stop <name> && docker rm <name>).
  • [x] Step 7: Launch via Compose: Run docker compose up -d within each stack folder (or click "Up" in the Compose Manager WebUI). Verify container logs.
  • [x] Step 8: Purge Legacy XML Templates: Delete obsolete templates from /boot/config/plugins/dockerMan/templates-user/ to prevent Unraid's autostart daemon from attempting to resurrect old containers.
  • [x] Step 9: Configure Disaster Recovery: Add /mnt/cache/appdata/compose to appdata.backup under includeFiles to bundle YAML files into weekly backups.
  • [x] Step 10: Test Host Reboot: Reboot Unraid to verify that Compose Manager autostarts all stacks in their declared DAG order without race conditions.

Conclusion

Migrating from Unraid's legacy XML templates to Docker Compose represents a major architectural milestone in homelab maturity. By trading ephemeral WebUI forms for version-controlled YAML manifests, you gain:

  • True Infrastructure-as-Code (IaC) with repeatable, Git-trackable state.
  • Deterministic startup graphs that eliminate timing race conditions between databases, VPN tunnels, and automation microservices.
  • Direct NVMe filesystem access that frees your SQLite databases from the crippling overhead of userspace FUSE (shfs).
  • Bulletproof VPN network coupling with guaranteed killswitches.
  • Full retention of the Unraid WebUI aesthetic via standardized container labels.

While you sacrifice the simplicity of one-click template updates in the GUI, you gain total operational control over your infrastructure. In a modern high-performance homelab, that is a trade well worth making.

Fahim

Fahim

Engineer, husband, dad, and photography enthusiast documenting technology, creativity, and the occasional rabbit hole.
Ottawa, ON