Deployment Modes#

MetaTana runs in three ways.

Desktop#

Desktop is best for:

• one user's local workstation
• direct folder picking
• drag-and-drop imports
• local preview and repair work

Desktop keeps its state in the platform's app data folder and can load optional .env files from there.

Docker#

Docker is best for:

• always-on hosts
• NAS or homelab installs
• browser access from another machine
• stable mounted media paths
• persistent data volumes

Docker path setup must be planned carefully because container paths can differ from host and playback-client paths.

Docker updates are image updates. Keep the persistent data volume mounted and recreate the service from the desired tag:

docker compose pull && docker compose up -d

When a Docker container is stopped or recreated, MetaTana stops its background work, saves its operation logs, and then exits.

The Docker image runs everything in one container by default (METATANA_RUNTIME_ROLE=unified). A split setup runs a web container and a background container from the same image version, with the same /app/data volume mounted in both.

In a split setup the web container only serves the app. Scans, folder watching, Autopilot, Scrape sessions, Arrivals, renames and Organize moves, NFO and artwork writes, artwork and subtitle fetches, and sync all run in the background container, so it must be running. A web container on its own accepts requests, such as starting a Scrape or approving renames in the Inbox, but leaves that work waiting.

These rules apply to Docker, NAS, and other server installs:

• Host names. MetaTana answers on IP addresses, localhost, one-word names such as nas, and local names such as nas.local or nas.lan with no setting. A reverse proxy, tunnel, or other domain name (for example metatana.example.com) gets 421 Misdirected Request until it is listed in METATANA_ALLOWED_HOSTS on the web container. The background container serves no pages and needs no change. See Your Own Domain Or Reverse Proxy.
• One account per install. The first MetaTana account that signs in becomes the owner. Other accounts see This MetaTana is linked to a different account. Reset it with docker exec metatana owner reset; in a split setup either container works, because both use the same database. See One Account Per Install.
• Claim code. Until an account is linked, MetaTana prints a one-time claim code to the server log every time it starts, and metatana owner claim-code shows it. The first sign-in from another device must enter it on the Enter the claim code screen. Installs that already have an owner are not affected.

The desktop app on its own computer is not affected by these rules.

Safety Limits#

Every install also follows these limits:

• Opening files. Play, Open folder, and other open actions only open files and folders inside your library. They refuse apps, installers, scripts, and shortcuts.
• Artwork fetches. Artwork URLs from an NFO file or a metadata provider cannot reach this computer or addresses on your local network, including after a redirect. Artwork that MetaTana itself serves still works.
• Framing. Other websites cannot show MetaTana pages inside a frame.
• Desktop updates. Installed desktop apps only download updates from the official https://updates.metatana.com feed.

Development#

Development mode is for contributors and local testing. Use the app's required Node version and the scripts in the app's repository.

Hosted Website And API#

The public website and hosted API run separately from your app. The website serves the marketing pages, docs, account, checkout, and device-link pages. The hosted API handles accounts, billing, device linking, email, and Skyhook.

Your media files and library stay in the app on your own computer or server.