Skip to content

Install on TrueNAS SCALE

Use a TrueNAS SCALE version with Compose-based Custom Apps to run Tuvima Library. Allow 10–20 minutes for configuration, plus downloads. Create storage datasets before opening the app editor.

Tuvima Library uses the published ghcr.io/tuvima/tuvima-library:latest image. If the NAS cannot download it, use the local source-build path and load that image on the NAS before deploying the app.

Prepare datasets

Create host-path datasets or directories such as:

/mnt/POOL/apps/tuvima/config
/mnt/POOL/apps/tuvima/db
/mnt/POOL/apps/tuvima/models
/mnt/POOL/apps/tuvima/artwork-cache
/mnt/POOL/apps/tuvima/backups
/mnt/POOL/apps/tuvima/transcode

Choose separate datasets for incoming and managed library media. Grant a numeric user and group—commonly the TrueNAS apps identity, UID/GID 568—the required access, then use those numbers for TUVIMA_UID and TUVIMA_GID.

Do not enable the Custom App Custom User override for this image. The container starts briefly as root to prepare bind-mount ownership, then its entrypoint drops to the configured non-root UID/GID before either Tuvima process starts.

Create the Custom App

  1. Open Apps → Discover Apps → Custom App.
  2. Choose Install via YAML or the Custom Config editor.
  3. Name the app tuvima.
  4. Download the full configuration from the Docker guide, then paste docker-compose.yml, replace all /mnt/user/... examples with the datasets created above, and set TZ.
  5. Save and deploy the app.
  6. Wait for the workload health state to become healthy.
  7. Open http://TRUENAS-IP:5016/setup, complete setup directly, and save the generated recovery codes.

Only Dashboard port 5016 belongs in the portal or port-forwarding configuration. Do not publish Engine port 61495.

TrueNAS performs basic YAML validation but does not validate application-specific values, so verify every host path and permission before importing media. See the official TrueNAS Custom App screen documentation.

Keep all persistent folders

Retain mappings for /library, /config, /db, /models, /artwork-cache, /backups, and /transcode. Reuse them when updating the container. An existing read-only media folder needs a separate mapping.

Claim your server

First-run setup is open to any device that can reach the server until the first administrator exists, so finish it before you open any router port.

  • Open /setup from any device on your home network. No setup code is needed.
  • Once the administrator exists, setup closes for good.

Next steps