Skip to content
MetaTana
On this page

Unraid Installation

MetaTana is published in Unraid Community Applications, so the quickest install is:

  1. Open Apps on your Unraid server.
  2. Search for MetaTana and select Install.
  3. Set your media path and app data path, then Apply.

The template fills in the image, port, and permissions for you. Continue to Create MetaTana And Add A Folder once it starts.

The rest of this guide is the manual Add Container route, and doubles as the field-by-field reference if you want to check or change anything the template set. You do not need a terminal, Docker Compose, or a separate database either way.

Prefer a copy-friendly visual walkthrough? Open the Unraid setup wizard. The values below are the detailed reference.

Before You Begin

You need an Unraid server with the array started and Docker enabled, the exact host path of your media share, an unused host port, an email address you can open, and outbound internet access for the image pull and email-code sign-in. If your firewall uses an allowlist, permit HTTPS to ghcr.io, pkg-containers.githubusercontent.com, api.metatana.com, and metatana.com.

This guide uses:

  • app data: /mnt/user/appdata/metatana
  • example media share: /mnt/user/Media
  • web port: 3000

Unraid paths are case-sensitive. Replace /mnt/user/Media with the exact share name shown under Shares.

1. Add The Container And Port

Open Docker → Add Container and enter the basic fields below. Leave unlisted fields at their defaults.

Unraid field Value
Name MetaTana
Repository ghcr.io/metatana/metatana-app:stable
Network Type Bridge
WebUI http://[IP]:[PORT:3000]/
Privileged Off

MetaTana publishes stable and versioned tags, but not a latest tag. Leave the Docker User override and Extra Parameters blank; in particular, do not add --user. The image prepares /app/data before dropping to the PUID and PGID configured below.

Add a Port entry:

Field Value
Name Web UI
Container Port 3000
Host Port 3000
Connection Type TCP

If port 3000 is already used, change only the Host Port, for example to 3001.

2. Map App Data And Media

Add a persistent Path for MetaTana state:

Field Value
Name App Data
Container Path /app/data
Host Path /mnt/user/appdata/metatana
Access Mode Read/Write

The container path must remain /app/data. This mapping preserves the database, settings, thumbnails, logs, and runtime state when Unraid recreates the container. Automatic library database backups are kept in /app/data/backups, which is /mnt/user/appdata/metatana/backups on the host.

Add a second Path for your library:

Field Value
Name Media
Container Path /media
Host Path /mnt/user/Media
Access Mode Read Only for scanning, or Read/Write for file changes

Use Read/Write only when MetaTana should write NFOs or artwork, rename, organize, or delete files. A Read Only path scans and is watched like any other, and Folders shows Read only with "Scans work, file changes are blocked". Mount only the shares MetaTana needs; do not map all of /mnt/user when a narrower share will do.

For separate shares, use distinct container paths:

Unraid host path Container path
/mnt/user/Movies /media/movies
/mnt/user/TV /media/tv

3. Add Runtime Variables

Add the first two Variable entries below. MEDIA_DIRS is shown for completeness, but the stable image already defaults it to /media, so it is optional when you use the container path in this guide.

Name Key Value
User ID PUID 99
Group ID PGID 100
Media roots (optional) MEDIA_DIRS /media
Allowed host names (optional) METATANA_ALLOWED_HOSTS Only if you open MetaTana through your own domain, for example metatana.example.com

99:100 is Unraid's usual nobody:users identity for share access. If your shares use custom ownership or ACLs, use IDs that already have the access you selected. Do not solve a permission error with chmod 777.

Leave METATANA_ALLOWED_HOSTS out when you open MetaTana by the server's IP address or by tower or tower.local. It is needed only when a reverse proxy (for example Nginx Proxy Manager or SWAG) or a tunnel serves MetaTana on your own domain. See Your Own Domain Or Reverse Proxy.

4. Create MetaTana And Add A Folder

  1. Confirm app data maps to /app/data, media maps under /media, and only intended media paths are writable.
  2. Select Create (or Apply if that is your Unraid version's label), keep the page open while the image downloads, then select Done.
  3. Back on Docker, open MetaTana → Logs and confirm startup settles without repeating permission or database errors.
  4. Open the WebUI at http://YOUR-UNRAID-IP:3000 or your chosen host port.
  5. Sign in with your email and the six-digit code sent to it, then select Choose a folder under Add your first folder on Home and follow Add Your First File Or Folder to make metadata ready and run the first scan. When it asks for a folder, choose /media, /media/movies, or /media/tv, not the Unraid host path.

The read-only media mapping keeps the first pass safe. MEDIA_DIRS does not add or scan a folder; you still add the folder with Choose a folder on Home. The scan stores results in /app/data; it does not change media files.

Docker sign-in state is stored by the browser for the exact WebUI origin. Changing the scheme, hostname, host port, or browser can require another email-code sign-in. That does not erase the library or settings kept in /app/data.

The first MetaTana account that signs in becomes this install's owner. Other accounts see This MetaTana is linked to a different 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 MetaTana → Logs every time it starts. You can also run metatana owner claim-code from the container Console. After you sign in, the screen shows Enter the claim code: type the code and select Link this MetaTana. Installs that already have an owner never ask for it.

To link a different account, open the Unraid Docker tab, select the MetaTana icon, choose Console, and run metatana owner reset. Or, from the Unraid terminal: docker exec MetaTana metatana owner reset. Then sign in with the new account and enter the new claim code that the command prints.

Confirm The Install

Open:

http://YOUR-UNRAID-IP:3000/api/health

If you chose a different Host Port, replace 3000 in this URL with that port.

A healthy response includes values such as "status": "ok", "runtimeRole": "unified", "releaseChannel": "stable", and "installSource": "docker".

Also confirm:

  • the WebUI returns after an Unraid stop/start
  • Folders can browse the expected paths under /media
  • the library remains after restart
  • a write test is attempted only on a read/write media mapping

After those checks pass, return to the Unraid Docker tab and switch MetaTana Auto Start to On so it returns after an array or server reboot.

Updates And Backups

Update the stable image safely
  1. Back up appdata first. Stop MetaTana and capture /mnt/user/appdata/metatana with your normal appdata backup workflow.
  2. Use Unraid's container update check and update MetaTana when offered.
  3. Reopen the WebUI and /api/health, then confirm the expected folders and library are still present.

Unraid offers an update only after the matching Docker image is published.

The update must preserve the mapping from /mnt/user/appdata/metatana to /app/data. New images can apply database migrations, so changing back to an older tag may also require restoring the matching appdata backup.

Back up or reinstall

For a filesystem-level backup, stop the container and include /mnt/user/appdata/metatana in the backup. Starting from a stopped container keeps the SQLite database and related files consistent.

The in-app settings backup is useful for transferring configuration, but it is not a replacement for a full /app/data backup.

MetaTana also backs up the library database every day and before an update changes it. The copies are in /mnt/user/appdata/metatana/backups and can be restored from Settings › Maintenance › Backups; the restore runs when the container next starts. See Back up your library. Those copies share the appdata disk, so keep including the whole appdata folder in your own backups.

For reinstall, reuse the same appdata host path and media mappings. A new appdata path creates an empty MetaTana library.

Troubleshooting

WebUI or startup problems

  • Confirm the container is running and read the first error in Logs.

  • Confirm the host port is not assigned to another container.

  • Browse to the Unraid server's IP and Host Port, not the container IP.

  • For database or permission errors, confirm app data is read/write, maps to /app/data, and uses the intended PUID and PGID values.

Media, write, or sign-in problems

  • If media is missing, verify the host path and capitalization, then add the container path under /media inside MetaTana.

  • If scanning works but file changes fail, change only the required media mapping from read-only to read/write.

  • If sign-in does not finish, confirm outbound DNS and HTTPS, keep using the same WebUI hostname, and leave the MetaTana tab open while you enter the six-digit code.

  • MetaTana was opened as "", which is not on its list of allowed host names. through a reverse proxy or your own domain: add that domain to METATANA_ALLOWED_HOSTS and apply. Opening http://YOUR-UNRAID-IP:3000 still works meanwhile.

  • This MetaTana is linked to a different account. Sign in with the account that set it up, or run metatana owner reset from the container Console.

  • Enter the claim code after sign-in: copy the code from MetaTana → Logs, or run metatana owner claim-code from the container Console.

Keep It Private

Bridge networking makes the WebUI available on your LAN. Do not forward the port directly from your router to the internet. For remote access, use a VPN or place MetaTana behind TLS and an access layer you control, and list that domain in METATANA_ALLOWED_HOSTS.

See Add Your First Folder, Environment Variables, and Scan Found Too Few Files for the next layer of detail.