Self Hosting

Self-Hosting (Web)

Run Tonkatsu Box in a browser on your own machine or home server. One Docker container serves the app and keeps the database, the cover cache and the API keys on the server, so every device on your network works with the same library.

It is the same app, not a cut-down version: collections, search, the episode tracker, tier lists, mood grids, statistics, import and export all work exactly as they do on the desktop.

Requirements

• Docker with Docker Compose

Nothing else - the web app is compiled inside the container, so you do not need Flutter on your machine.

Install and run

git clone https://github.com/hacan359/tonkatsu_box.git
cd tonkatsu_box
docker compose up -d --build

The first build takes several minutes. Then open:

http://<server-ip>:8080

Configuration (optional)

Copy .env.example to .env next to docker-compose.yml and uncomment what you need. Without a .env everything uses defaults.

Variable	Default	What it does
TONKATSU_DATA_PATH	./data	Host folder with all server data
TONKATSU_PORT	8080	Port the web UI answers on
PUID / PGID	1000 / 1000	Owner of the files in the data folder
TONKATSU_KEY_*	-	API keys, e.g. TONKATSU_KEY_TMDB
TONKATSU_AUTH	off	token makes the web UI ask for an access token
TONKATSU_AUTH_TOKEN	generated	Your own token instead of the generated one
TONKATSU_BIND	0.0.0.0	Host interface the port is published on
TONKATSU_IMAGE_HOSTS	any	Hosts covers may be fetched from, comma-separated

API keys can also be entered in the app itself (Settings → API Keys) - they are stored on the server in data/keys.json. Keys set via .env override keys.json.

External catalogs are called by the server, not by your browser: the container adds the real credentials and the proper user agent, so no key ever reaches a browser tab and CORS is never in the way.

Access token (optional)

By default the server has no login: anyone who can reach the port can use the library. For a server that other devices can reach, set TONKATSU_AUTH=token in .env. The server then prints a sign-in link on every start:

docker compose logs tonkatsu | grep "Sign in"
# Sign in: http://localhost:8080/?token=…

Open that link with the server's address instead of localhost: the browser stores the token and removes it from the address bar. A browser without the token is shown a screen to paste it into, and Settings → API Keys lets you change it later. The token is kept in data/auth_token; delete the file and restart to issue a new one, or set your own with TONKATSU_AUTH_TOKEN.

TONKATSU_BIND=127.0.0.1 publishes the port on this machine only. TONKATSU_IMAGE_HOSTS limits which hosts the server fetches covers from, as a comma-separated list of domains (subdomains included). Leave it empty unless you need it: a cover host missing from the list shows as a broken image.

Files

Path	What
.env	Your local configuration (not committed)
data/tonkatsu_box.db	The database
data/keys.json	API keys entered in the app
data/auth_token	The access token, when TONKATSU_AUTH=token
data/images/	Cover cache
data/snapshots/	Automatic DB snapshots taken before migrations

Backup

Copy the data/ folder while the container is stopped - that is the whole backup. There is also Settings → Backup in the web UI, which downloads a portable archive to whatever device you are browsing from. See Data, Sync & Backup.

Update

git pull
docker compose up -d --build

Pending database migrations run on start; a snapshot of the old database is saved to data/snapshots/ first.

HTTPS and a custom domain (optional)

Caddy in front gives https://tonkatsu.box, HTTP/2 and PWA install support:

# .env: TONKATSU_DOMAIN=tonkatsu.box (default), keep TONKATSU_PORT at 8080
docker compose -f docker-compose.yml -f docker-compose.caddy.yml up -d

1. Point the domain at the server: an entry in the router's DNS, or in hosts (<server-ip> tonkatsu.box) on each device.
2. Trust Caddy's local root certificate once per device - the file is data/caddy/caddy/pki/authorities/local/root.crt (on Windows: double-click → Install Certificate → Trusted Root Certification Authorities).

Plain HTTP keeps working without any of this - Caddy is an add-on, not a requirement.

Not available in the browser

These features need the desktop or the Android app:

• VGMaps (needs WebView2, Windows only)
• Discord Rich Presence
• Kodi sync
• Gamepad navigation
• Device-to-device LAN sync
• User profiles - the server holds one library
• Custom data folder - the location is TONKATSU_DATA_PATH instead

Everything else works as in the desktop app.

Notes

• The web build has no accounts; TONKATSU_AUTH=token makes it ask for a single access token. Keep it on your LAN or behind HTTPS - do not put it on the open internet without the token.
• The browser holds no database at all: every read and write is a call to the server, so two devices never fall out of sync.