Skip to content
On this page

TrueNAS Installation

MetaTana is listed in TrueNAS Community Apps. Install it from the TrueNAS Apps screen so TrueNAS manages the container, storage, and updates.

Using CasaOS? The CasaOS App Store listing has been submitted and is waiting for approval; it is not live yet. Use the Docker installation guide on CasaOS for now.

1. Prepare Your Datasets

  • App data: let TrueNAS create it (the default ixVolume), or create a dataset such as /mnt/tank/apps/metatana if you want to manage and snapshot it yourself.
  • Media: use the dataset that already holds your movies and TV, for example /mnt/tank/media.

MetaTana runs as the TrueNAS apps user and group (568) by default. That user needs read access to the media dataset to scan it, and write access only if you later want MetaTana to write NFO, artwork, or renamed files. A read-only dataset scans and is watched like any other, and Folders shows Read only with "Scans work, file changes are blocked".

TrueNAS starts every app with UMASK 002, so the folders and files MetaTana writes into a writable dataset can be changed by the whole apps group, not only by MetaTana.

2. Install The App

Set Media Storage to Host Path TrueNAS fills in Media Storage as an ixVolume, which is a new, empty dataset. Change Type to Host Path and select the dataset that already holds your movies and TV, or the first scan finds nothing.

Open Apps → Discover Apps, search for MetaTana, and select Install. Fill in the form:

Section Field Value
MetaTana Configuration Timezone Your timezone
MetaTana Configuration Additional Environment Variables Leave empty unless you need one from Environment Variables. Add METATANA_ALLOWED_HOSTS only if you will open MetaTana through your own domain (details).
User and Group Configuration User ID / Group ID 568 / 568 (the TrueNAS apps user), or IDs that already have access to your media
Network Configuration WebUI Port → Port Number 30457 (default), or any free port
Storage Configuration Data Storage ixVolume, or Host Path set to your app-data dataset. Mounted in the container at /app/data.
Storage Configuration Media Storage Required change: set Type to Host Path and Host Path to the dataset that holds your library, for example /mnt/tank/media. Mounted in the container at /media.
Storage Configuration Additional Storage Optional. Add more media datasets with a Mount Path such as /media2. Turn on Read Only for a scan-and-review trial.

Select Install and wait until the app shows Running.

3. Sign In And Add A Folder

Open the WebUI from the app's Web UI button, or go to http://YOUR-TRUENAS-IP:30457 (use your port if you changed it). Then follow Add Your First File Or Folder.

The first MetaTana account that signs in becomes this install's owner; other accounts see This MetaTana is linked to a different account. See Change The Linked Account.

The first sign-in asks for a claim code. Until an account is linked, MetaTana prints a one-time code such as ABCD-EFGH to the app's log every time it starts. After you sign in, the screen shows Enter the claim code: type the code and select Link this MetaTana. To show the code again, open System → Shell, find the container with sudo docker ps, and run:

sudo docker exec <container> metatana owner claim-code

Installs that already have an owner never ask for the code.

When MetaTana asks for a folder, enter the container path: /media, or a folder inside it such as /media/Movies. Do not enter the TrueNAS host path (/mnt/tank/media); MetaTana cannot see it.

The first scan stores results in /app/data. Media files stay where they are unless you choose Tidy into Movies and TV folders for the folder and mount the media dataset read/write.

Confirm The Install

Open http://YOUR-TRUENAS-IP:30457/api/health. A healthy response includes "status": "ok".

If the app stops right after it starts and its log says MetaTana cannot write to /app/data as 568:568. Check the data volume permissions and PUID/PGID, then restart., the app-data dataset belongs to another user: a new Host Path dataset is owned by root, and one copied from a plain Docker install is owned by 1001. Give the app's user (568, or the User ID you chose) write access in Datasets → Edit Permissions, then start the app again. Nothing in the dataset was changed. An ixVolume is set up for the app's user already.

If Choose a folder or No videos found says This mounted folder is empty, Media Storage is still an ixVolume or points at an empty dataset. Open Apps → MetaTana → Edit, set Media Storage to Host Path with your library's dataset, and save.

If a folder does not appear or a scan reports Permission denied, check that the media dataset is mounted as a Host Path at /media and that the User ID / Group ID you chose can read it. See Install and sign-in problems.

Your Own Domain Or Reverse Proxy

Opening MetaTana by the TrueNAS IP address, by truenas, or by truenas.local needs no setting. A reverse proxy or tunnel on your own domain (for example metatana.example.com through Nginx Proxy Manager) shows MetaTana was opened as "metatana.example.com", which is not on its list of allowed host names. until you list the domain. Open Apps → MetaTana → Edit, and under Additional Environment Variables add:

Name Value
METATANA_ALLOWED_HOSTS metatana.example.com

Save to redeploy the app. Separate several names with commas. See Your Own Domain Or Reverse Proxy for wildcards and proxy settings.

Change The Linked Account

To link a different MetaTana account, open a TrueNAS shell (System → Shell), find the container with sudo docker ps, and run:

sudo docker exec <container> metatana owner reset

Then sign in with the new account and enter the new claim code that the command prints. The account that enters it becomes the owner, even while the install still holds the old owner's session for background work. metatana owner status shows whether an account is linked.

Updates

Update from Apps → MetaTana → Update when TrueNAS offers a new version. Back up the app-data dataset or ixVolume first. The TrueNAS catalog is maintained outside MetaTana, so a new MetaTana release can reach TrueNAS later than the Docker image.