Install prdb-fab on TrueNAS as a Custom App

prdb-fab connects prdb.net, your Usenet indexers and SABnzbd to build an organised media library. On TrueNAS, you can run it as a Custom App using Docker Compose YAML. This guide takes you from storage preparation to the first completed setup.

The instructions target the Docker-based Apps system introduced in TrueNAS SCALE 24.10, including subsequent Community Edition releases. Use a supported TrueNAS release with that Apps system; this is not a TrueNAS CORE jail or an older Kubernetes Apps guide. Menu labels can vary by release. TrueNAS documents the two custom-app installation paths in its Apps reference.

The example uses prdbnet/prdb-fab:0.21.0, the version pinned in the project’s Docker guide when this article was written. Check that guide and the releases when choosing a version.

1. Have the essentials ready

You need an Apps pool configured in TrueNAS, space for application data and media, and a prdb.net API key with an active API plan. Free web browsing does not include API access; see the plan comparison. The NAS also needs outbound access to pull the container image and connect to prdb.net.

To download anything, you also need a working SABnzbd installation configured with a Usenet provider, plus an indexer with API access. Have the SABnzbd address, API key, category and completed-download path ready, along with the indexer address and key. You can skip those connections during initial setup and add them later.

2. Prepare storage and permissions

The following layout is an example. Replace tank with your pool name and adapt the directories to your existing storage:

TrueNAS host path	Purpose	Path inside prdb-fab
`/mnt/tank/apps/prdb-fab`	Dedicated application dataset: database, settings, logs and artwork	`/data`
`/mnt/tank/media`	Media dataset shared with the download workflow	`/media`
`/mnt/tank/media/downloads/complete`	Completed SABnzbd downloads	`/media/downloads/complete`
`/mnt/tank/media/library`	Destination for the organised library	`/media/library`

Create the application and media datasets under Datasets, and create the two subdirectories inside the media dataset before installing the app. Existing directories are fine. Keeping downloads and the library as ordinary directories in the same dataset allows moves within one filesystem; separate child datasets are separate filesystems.

Keep the application dataset local to TrueNAS. /data contains SQLite state and must not point to a remotely mounted SMB or NFS share. Use a dedicated dataset because the container takes ownership of its application data at startup.

Choose the local user and group that should own files written by prdb-fab. For an existing media user named media, the TrueNAS system shell can show its numeric IDs:

id -u media
id -g media

Replace media with your actual account name. Put the resulting numbers into PUID and PGID below; 1000 is only an example, not a TrueNAS default.

Use the dataset permissions or ACL editor to grant that identity traversal through the parent directories, read/write access to completed downloads, and read/write access to the library. prdb-fab moves files, so reading a finished download alone is insufficient. SABnzbd must create downloads that this identity can read and move. Sharing an appropriate media group and using inheritable group permissions is one way to arrange that. Avoid replacing existing media ACLs recursively just to make the container start.

3. Install the Custom App with YAML

In TrueNAS, open Apps → Discover Apps. Open the three-dot menu near Custom App and choose Install via YAML. Name the application prdb-fab and paste the Compose definition below. This is the YAML installation path, rather than the guided image-fields form opened by the Custom App button itself. See the official custom-app instructions.

services:
  prdb-fab:
    image: prdbnet/prdb-fab:0.21.0
    restart: unless-stopped
    ports:
      - "18080:8080"
    environment:
      PUID: "1000"
      PGID: "1000"
      UMASK: "022"
    volumes:
      - type: bind
        source: /mnt/tank/apps/prdb-fab
        target: /data
        bind:
          create_host_path: false
      - type: bind
        source: /mnt/tank/media
        target: /media
        bind:
          create_host_path: false

Replace the two source paths and the user/group IDs before installing. The bind mounts require the directories to exist, which helps catch a mistyped path. Both mounts are writable: prdb-fab needs to maintain its state and file downloaded media.

Port 18080 is the example host port; change it if another app already uses it. Keep the container port on the right as 8080. Leave the image’s entrypoint and container user at their defaults: the entrypoint prepares /data, then runs the application as the PUID/PGID identity. Do not add a Compose user: override.

There is no API key in this YAML. prdb-fab asks for it in the browser and stores the configuration in /data.

Click Install and wait for the application to start. Open http://YOUR-TRUENAS-IP:18080 from your trusted local network, substituting your NAS address. Set the initial password immediately: the first visitor to an unconfigured installation chooses it. There is no default username or password. Plain HTTP does not encrypt credentials; use HTTPS through a reverse proxy or a protected VPN connection when accessing the app beyond your trusted LAN.

4. Complete the first-run wizard

The wizard saves each completed step and checks the connections you supply:

prdb API key: enter your prdb.net key. This step is required and must pass validation before setup can proceed.
SABnzbd: enter its reachable address, API key, download category and the finished folder as seen inside prdb-fab. You can skip this step if SABnzbd is not ready yet.
Indexers: add your indexer addresses and API keys. Each is checked with a real search. This step can also be skipped and completed later in Settings.
Library root: enter /media/library for this example. This required directory must be writable by the configured identity.

For a SABnzbd app published on the same NAS, use its reachable NAS address and published port, for example http://YOUR-TRUENAS-IP:18081 if that is how you configured SABnzbd. localhost inside prdb-fab refers to prdb-fab’s own container. Separate TrueNAS apps do not automatically share Compose service-name resolution.

Make the SABnzbd paths agree

Both applications need access to the same completed files, even if their container paths are different. The simplest arrangement is to mount /mnt/tank/media as /media in both applications and configure SABnzbd’s category to finish under /media/downloads/complete. Then prdb-fab uses that same path.

If your existing SABnzbd app instead mounts the host’s completed folder as /downloads, the relationship is:

View	Completed-download folder
TrueNAS host	`/mnt/tank/media/downloads/complete`
Existing SABnzbd container	`/downloads`
prdb-fab container in this guide	`/media/downloads/complete`

Configure the SABnzbd path mapping in prdb-fab so the finished folder SABnzbd reports resolves to /media/downloads/complete. For example, a job reported beneath /downloads/job-name must resolve beneath /media/downloads/complete/job-name. Entering the host path /mnt/tank/... in prdb-fab will not work with these mounts.

5. Verify the first run

Setup ends on the wanted list while the initial catalogue work runs in the background. Open Status to follow it. With an indexer enabled, the app fills its rolling 90-day Recent Window; this is incremental, so an incomplete first fill is not by itself a failed installation.

Before enabling automation, select one eligible release and follow a manual download through SABnzbd, collection and filing. Confirm that the result appears beneath /mnt/tank/media/library on the NAS. A safely identified entry gets a Jellyfin-compatible folder and movie.nfo, with artwork when available. Files needing a decision appear in the review queue.

Review Settings → Reporting as part of setup. Fulfilment reporting and confirmed file-assignment reporting are independently enabled by default. The project’s privacy documentation explains their contents and how to turn either channel off.

If something does not work

Symptom	What to check
The app will not start	TrueNAS app logs, image tag, existing bind-mount paths and whether host port `18080` is free.
The library is not writable	`PUID`, `PGID`, parent-directory traversal and the media dataset’s permissions or ACLs.
SABnzbd connection fails	Its published address and port, API key and reachability from prdb-fab; avoid `localhost`.
A completed download cannot be collected	Whether both apps see the same files, finished-folder mapping and download permissions.
The prdb key is rejected	The key and its API access; a free browsing account alone is insufficient.
Catalogue or indexer work is incomplete	Status details, connectivity and API limits; let the initial background fill progress.

Back up before updating

Use Settings → Backup to export the installation’s non-recoverable state before changing the image tag. The export contains readable credentials, including API keys, so keep it in protected, encrypted backup storage. It does not contain your video files or replace a media backup. For a dataset-level snapshot of /data, stop the app first so the database is quiescent.

To update, review the release notes, edit the Custom App YAML to the chosen pinned image tag, and save/redeploy through TrueNAS. Keep the same datasets mounted. Verify Status and your library after startup. Restore from the portable backup is offered on a fresh, empty installation; the project documentation explains that process.

Once filing works, you can mount the finished library read-only in prdb-viewer and give it its own application-data directory. Our overview of prdb-fab and prdb-viewer explains how the two fit together.