Configuration
Almost everything in Plinthio is set in the app. Environment variables only control how the container runs: ports, folders and security switches. There's no config file to edit.
Environment Variables
Set these in a .env file next to docker-compose.yml, or under environment: in the compose file. After changing them, run docker compose up -d to apply.
Read by the Compose Files
| Variable | Default | What it does |
|---|---|---|
MEDIA_DIR | /media/library | Host folder mounted at /media in the container |
BIND_ADDRESS | 0.0.0.0 | Host address the ports are published on. 127.0.0.1 makes Plinthio reachable only from the server itself |
PLINTHIO_TAG | latest | Image tag, which chooses the updates you take. See Updating |
TZ | UTC | Time zone for logs and scheduled jobs |
PUID / PGID | 1000 / 1000 | User and group the server runs as, and that own /config |
TLS_HOSTNAMES | none | Extra IPs and names for the built-in HTTPS certificate, comma-separated, e.g. 192.168.1.20,nas.local. Usually unneeded. A public domain must be set before the first start |
BACKUP_DIR | none | Host folder for a second copy of backups, mounted at /backups once you uncomment that line in the compose file. See Administration |
TS_AUTHKEY | none | Tailscale add-on: an auth key for the first sign-in |
TS_HOSTNAME | plinthio | Tailscale add-on: the machine's name on your tailnet |
TS_FUNNEL | false | Tailscale add-on: true opens the .ts.net address to the internet. Must be exactly true or false |
PLINTHIO_DOMAIN | none | Public-address add-on: the name guests use, e.g. media.yourdomain.com |
COMPOSE_FILE | docker-compose.yml | Docker Compose's own setting: which files make up the stack, e.g. docker-compose.yml:docker-compose.tailscale.yml, so add-ons stay on across updates |
The add-ons are described in Away From Home.
Read by the Server
| Variable | Default | What it does |
|---|---|---|
PORT | 8080 | HTTP port inside the container. Leave it alone and change the published port instead |
HOST | 0.0.0.0 | Interface the server listens on |
DATA_DIR | /config in Docker, ./data without Docker | Where the database, covers, caches and backups live |
HTTPS_PORT | 8443 in Docker, off without Docker | Port for the built-in HTTPS server, next to plain HTTP. Empty turns it off |
TLS_CERT / TLS_KEY | /config/ssl/cert.pem and key.pem if present | Your own certificate and key instead of the generated ones |
TRUST_PROXY | off (loopback with the add-ons) | Set only when Plinthio sits behind a reverse proxy or tunnel, so rate limits, logs and the away-from-home checks see real client addresses. Prefer the proxy's address or subnet (e.g. 172.18.0.5 or 172.18.0.0/16) over 1. Also accepts a hop count, true, or an IP list |
JWT_SECRET | generated | Secret that signs sign-ins. By default a random one is made on first start and kept in /config/jwt.secret. Don't put a literal secret in the compose file |
JWT_EXPIRES_IN | 7d | How long a sign-in lasts without the app being opened. The app renews it on every load |
MEDIA_TOKEN_EXPIRES_IN | 24h | Lifetime of the media-only token used in image, audio and video links |
CORS_ORIGIN | * | Allowed browser origins for the API |
CSP | on | Content-Security-Policy. report-only logs violations without blocking, off disables it. Only change it to diagnose a blocked resource |
HLS_CACHE_MAX_AGE_HOURS | 24 | How long converted video segments and other temporary media caches stay on disk after their last use |
TMDB_API_KEY | none | TMDB key used when none is saved in the app. A key saved in the app wins |
UPDATE_CHECK | on | false stops the twice-daily check for new releases, and with it the admin update banner |
UPDATE_CHECK_URL | GitHub releases API | Where the update check looks. For testing |
APP_VERSION | from package.json | Overrides the reported version. For development builds |
WARNING
Never set TRUST_PROXY without a proxy in front of Plinthio. Clients could then fake their address, get round rate limits, and appear to be at home.
Settings in the App
Admin settings save as you change them, with "Saved" shown beside them. Backups and custom CSS have a Save button. Each section is described in Administration.
| Section | Setting | Default | What it controls |
|---|---|---|---|
| Libraries | Automatic scanning | on, every hour, watcher on | Re-scan on a schedule (every 15 minutes, 30 minutes, hour, 6 hours or day) and Watch folders for changes, which scans about 30 seconds after a file appears |
| Metadata | TMDB key | not set | Checked against TMDB when saved. MangaDex, Google Books and Open Library need no key |
| Kids Mode | Whole libraries | off | Makes everything in a library visible to kids accounts |
| Appearance | Let people personalize | on, each allowed | Whether people can choose their own accent colour, navigation, page width and pause screen. One switch for all, plus Users can change on each |
| Appearance | Accent colour | Zinc | One of 16 colours, for anyone who hasn't picked their own |
| Appearance | Navigation | Top Navigation | Top Navigation or Sidebar |
| Appearance | Page width | Full Width | Full Width, or Contained (centred, up to 1440px) |
| Appearance | Pause screen | Details | Simple, Details, Cinematic or Bedtime. See Movies and Shows |
| Appearance | Server name and sign-in notice | "Plinthio", no notice | The name shown in the app and browser tab, and a message on the sign-in page |
| Appearance | Custom CSS | empty | CSS applied for every user. The in-app docs page Custom CSS Styling lists the variables |
| Features | Shelf views | all on | Whether Disk Folders and Custom Folders are offered. Alphabetical and Creator are always there |
| Features | Ratings | all on | Personal stars, the server average, and TMDB's score. A switched-off rating isn't sent by the API either |
| Features | Show missing films in collections | on | Collections also list films the server doesn't have, greyed out with a Request button |
| Features | Watch parties | off | Adds Watch Together to movies and episodes. Turning it off ends any party in progress |
| Playback | Hardware acceleration | Whatever is found | Auto-detect, a specific method (VAAPI, QuickSync, NVENC), or Always the CPU. Test runs a short real conversion |
| Playback | Opening sequence | off | A short clip before movies and episodes. See Movies and Shows |
| Network | Allow access from outside the home network | chosen in the setup wizard | Off: only home and Tailscale addresses can sign in or use anything |
| Network | Tailscale devices count as home | on | Off treats Tailscale addresses as outside |
| Network | Require two-factor away from home | off | Sign-ins from outside need a two-factor code |
| Backups | Back up on a schedule | on, daily, keep 7 | Every 6 hours, 12 hours, daily, every 3 days or weekly, keeping 1–30. Plus a second place to copy them to |
The Appearance section shows a live preview of the shelf, a title page, the sign-in screen and the pause screen. Hovering a choice previews it before you pick it.
Servers upgraded from a version before 1.4.0 keep Allow access from outside the home network on, so they keep working as before.
Per-Title Settings
Editors and admins can change these from a title's page:
- Edit Metadata: search providers and apply a match to one title or a whole series, or upload a cover.
- Series settings: display name, reading direction (manga) and age rating.
- Kids: adds the series or title to Kids Mode.
See Libraries.
Per-Person Settings
Everyone has their own Settings, described in Your Settings. Admins set each account's role, content limit, Kids Mode, expiry and away-from-home access in Admin → Users. See Accounts and Access.