Unraid deployment

Unraid Community Applications (CA) templates for TorrentNG. See deploy/README.md for the underlying Docker images and docs/DEPLOYMENT.md / docs/NATIVE_DEPLOYMENT.md for the non-Unraid deployment paths these templates wrap.

The Community Apps submission files live at the repository root and in /templates/; deploy/unraid/ contains this documentation only. Use the root template URLs below so the Community Apps scan sees exactly the two maintained templates.

Which template

• Already running rTorrent, qBittorrent, Transmission, or Deluge (on this box or elsewhere on the network) and just want a modern replacement WebUI and a qBittorrent-compatible API for Prowlarr/Sonarr/Radarr/autobrr/ cross-seed? Use torrentng-webui.
• Want one box that does everything with no external client dependency? Use torrentng (runs torrentngd, TorrentNG's own first-party engine).

Both are documented in depth in their own <Overview> text, which Unraid shows on the Add Container page.

Try it without submitting anywhere (works today)

Unraid can install directly from a raw template XML URL, no CA submission or review required:

1. Docker tab -> Add Container.
2. In the Template field at the top, paste the raw GitHub URL of the template you want, e.g. https://raw.githubusercontent.com/snapetech/TorrentNG/main/templates/torrentng-webui.xml.
3. The form populates from the template. Fill in the required fields (Secret Key, API Tokens, and the backend URL/credentials for torrentng-webui; the API Token and Config path for torrentng) and Apply.

This is enough for personal use or sharing a direct link with other TorrentNG users before/without a formal CA listing.

Getting listed in Community Applications

Full discoverability goes through https://ca.unraid.net/submit. The Community Apps portal scans a repository as a unit: ca_profile.xml is at the repository root, and each Docker app has one XML under templates/. TorrentNG now uses that layout directly in this repository, so a scan finds both app templates as entries under one publisher profile.

If the native template is already submitted from this repository, the WebUI template is included in the same repository scan; it does not need a second submission. To publish the WebUI as a separate repository/listing, create a dedicated public repository containing its own root ca_profile.xml, icon.png, and only templates/torrentng-webui.xml, then change its profile text to describe the WebUI app alone. Update the raw GitHub URLs in the profile and template, especially <Icon> and <TemplateURL>, to point at the new repository.

Before submitting or rescanning:

• Push icon.png, ca_profile.xml, and the templates so the raw URLs referenced in the XML resolve.
• Run Validate then Scan at https://ca.unraid.net/submit and fix anything it flags. Confirm both app names appear in the preview.
• Confirm the repository has an OSI-approved license covering the submitted templates and metadata. TorrentNG's root LICENSE applies to this repository.

Design notes for future edits

• Multi-backend template, no conditional fields. Unraid templates can't show/hide <Config> entries based on another field's value, so torrentng-webui.xml lists every backend's variables with Display="advanced" and per-field descriptions saying which "Backend Type" selection they apply to, following the same pattern used by multi-provider templates like binhex's VPN-enabled containers.
• Both images accept runtime PUID/PGID. The Unraid templates default to the standard nobody:users identity, 99:100; generic Docker/Compose deployments default to 1000:1000. The entrypoint starts with the minimal setup privileges needed to assign the small internal runtime directory roots, then launches Tini and the TorrentNG process as the selected non-root identity. It never recursively chowns a mounted download tree.
• Do not set --user in <ExtraParams>. The entrypoint needs its short setup phase. A direct Docker --user override bypasses that phase and will fail when the selected identity cannot write /run/rtorrent, /var/log/rtorrent, /run/secrets, or the state directory. Set PUID and PGID instead. The mounted Data/Downloads and Config/State paths must already be accessible to that identity; for the default template paths use Unraid's Tools -> New Permissions, or: chown -R 99:100 /mnt/user/downloads/torrentng /mnt/user/appdata/torrentng for the native template, and chown -R 99:100 /mnt/user/downloads /mnt/user/appdata/torrentng-webui for the WebUI template. If the WebUI Data path is shared with another torrent client, preserve that client's access too.
• torrentngd has no per-field env var overrides by design (see crates/rt-config), unlike the compatible-client service. Its Unraid template (torrentng.xml) and deploy/native/entrypoint.sh bridge this with exactly two additions: default TORRENTNGD_CONFIG to a /config directory mount (falling back to the packaged default config if nothing is mounted there), and an optional TORRENTNGD_API_TOKEN env var that gets written to the path the packaged config already expects for auth.api_tokens_file. This does not change torrentngd's documented file-based configuration convention -- power users can still mount a fully custom config.toml and set TORRENTNGD_CONFIG themselves exactly as deploy/native/compose.yml does.
• Fronting an existing rTorrent needs TNG_RTORRENT_MANAGED=0. Before this template existed, the compatible-client service's entrypoint.sh always launched and owned its own rTorrent process whenever TNG_BACKEND=rtorrent -- there was no way to point it at an rTorrent instance the operator already runs, unlike qBittorrent/ Transmission/Deluge, which were always network-address-based. See the TNG_RTORRENT_MANAGED handling added to deploy/docker/entrypoint.sh (default 1, matching every existing compose profile's behavior unchanged; the Unraid template sets it to 0).
• Tracker identity. The compatible-client service pushes its User-Agent/peer_id to whatever rTorrent it connects to on every start (docs/TRACKER-IDENTITY.md). Both templates carry that warning verbatim in their <Overview>/field descriptions -- don't trim it out when editing; a shared/hardcoded peer_id previously got a real user banned from a private tracker.
• The rTorrent backend hard-fails on startup if it can't reach/identify rTorrent; the other three don't. Verified by actually running the container against an unreachable SCGI address: after 3 retries over ~15 seconds it logs "refusing to serve until rTorrent tracker identity is applied" and the process exits -- Docker/Unraid's restart policy then crash-loops it. qBittorrent/Transmission/Deluge instead come up immediately and just report "status":"degraded" on /health while retrying the backend in the background. This is existing, intentional behavior in the compatible-client service (the identity push is a safety gate, not a bug), but it means the rTorrent SCGI address has to be correct before first start, unlike the other three backends where you can fix it after. Documented on the "SCGI TCP Address" field.
• Published-image cadence. These runtime and template behaviors were verified against locally built images from current source, not asserted from reading the Dockerfiles. The templates use :latest, but the release workflow publishes that tag only from a main-* release tag; a commit on main alone does not update GHCR. After changing deployment behavior, push a release tag, wait for the image workflow to complete, and verify the native and sidecar package pages before installing from the raw template URLs.