Install on Unraid

Before you start#

tofa runs on Unraid as a normal Docker container. Two Unraid-specific choices matter, and both are easy to get right on the first install:

• Where tofa's own data lives. The safe default is /mnt/user/appdata/tofa, matching other Unraid media servers and working with any pool name. Keep the appdata share on a fast pool. For the best database performance, make appdata an exclusive share or point tofa directly at the real pool path, such as /mnt/main_cache/appdata/tofa.
• Who tofa runs as. Unraid's shares and appdata are owned by the nobody user (id 99) and the users group (id 100). Set PUID=99 and PGID=100 and tofa takes care of the rest, including fixing ownership of its own data folder on every start. It never changes ownership of your media.

Your media itself is fine on a normal share like /mnt/user/media.

Install from the Apps tab#

tofa is in Community Applications. Open the Apps tab, search for tofa, and click Install. The template fills in everything above for you:

• Config (/data) is set to /mnt/user/appdata/tofa.
• Media (/media) is set to /mnt/user/media. Point it at wherever your library lives, and set the mode to Read Only if tofa should never delete files from disk.
• PUID and PGID are set to 99 and 100 under Advanced View.

Click Apply. The first start takes a minute or two while tofa sets up its database.

Host networking is what lets devices on your network connect to tofa directly, and lets tofa ask your router for a port for remote access. tofa uses port 33333, which avoids the default ports of Plex, Jellyfin, and Emby, so it can run alongside them.

Adding it by hand instead#

If you would rather not use Community Applications, open the Docker tab, click Add Container, and set: Name tofa, Repository ghcr.io/tofatv/tofa:beta, Network Type Host, Extra Parameters (under Advanced View) --init. Add a path for /data pointing at /mnt/user/appdata/tofa, a second path for /media pointing at your media share, and two variables, PUID = 99 and PGID = 100.

Claim your server#

Open a browser on any device on your network to:

http://YOUR-UNRAID-IP:33333

Sign in with your tofa account and claim the server. It picks up its secure certificate on its own moments after the claim, so there is no need to restart the container. The full claim walkthrough, including claiming from another device, is in Run your tofa server.

Add your media#

In the web interface, add a library and point it at your media inside the container: /media, or a subfolder like /media/Movies. tofa scans, matches, and fills in artwork on its own.

Hardware transcoding#

• Intel or AMD (including iGPUs): in the container settings, add a Device with /dev/dri as both the host and container path. Then use Settings, then Transcoding, then "Test hardware" in the tofa web interface.
• NVIDIA: install the Nvidia Driver plugin from Community Applications, then in the container settings set Extra Parameters to --init --runtime=nvidia, and add two variables: NVIDIA_VISIBLE_DEVICES = all and NVIDIA_DRIVER_CAPABILITIES = compute,video,utility.

Updates#

When a new build is out, tofa shows an update banner in the web interface. To apply it, use force update on the container in the Docker tab (turn on Advanced View to see it). Your data and settings live in your appdata path and survive updates.

If something is off#

• Apply fails with docker: bad format for path. An early version of the template shipped an empty Device row for /dev/dri, and Unraid passes an empty device straight to Docker, which refuses it. Edit the container, turn on Advanced View, and remove that empty Device row, or fill it in with /dev/dri if you have an Intel or AMD GPU. The row is gone from our template, but Community Applications serves a cached copy and can keep offering the old one for a day or two, so check for the row before you click Apply. Unraid also saves your own copy of the template once you have applied it, so an install that already failed keeps the row until you remove it by hand.
• Hardware transcoding says permission denied. tofa gives itself the group that owns your /dev/dri devices on start, so adding the Device row is normally all it takes. If it still cannot reach the card, run ls -l /dev/dri from the Unraid terminal. Devices owned by root rather than by a render or video group need that group named explicitly in Extra Parameters, as --group-add <id>.
• The container stops right after starting. Check its log from the Docker tab. If you see a permissions message, confirm PUID and PGID are set (99 and 100) and that your appdata path is /mnt/user/appdata/tofa or a real pool path.
• My media isn't showing up. Check the /media path mapping points at the right share, and that the nobody user can read those files. Files moved onto the array by other tools occasionally end up with odd ownership; Unraid's New Permissions tool (Tools tab) resets a share to nobody:users.
• Playback stutters on big files. Check hardware transcoding above. Keep the appdata share on a fast pool and enable exclusive access, or map Config directly to that pool.
• Port 33333 is already in use. Something else on the host claimed it. Stop that service, or switch the container off host networking and map a different port, as described in Run your tofa server. Off host networking tofa can't detect your server's address by itself, so also set your Unraid server's IP as the local network address under Settings, then Remote Access; that keeps devices at home connecting directly. (The template's advanced view has an ADVERTISED_LAN_IP variable that does the same thing, if you'd rather keep it with the container config.)

Still stuck? Getting help & feedback covers what to send us.