Installation

This page takes you from an empty machine to a running Plinthio server, through the setup wizard, and onto your phones.

What You Need

• A machine that runs Docker: a Linux box, NAS or mini PC, a Mac, or Windows with Docker Desktop. Images are published for x86-64 and ARM64 (Raspberry Pi 4 and 5, Apple Silicon, most NAS boxes).
• Your media in folders Docker can read. Plinthio only reads your media folders. It never renames, moves or writes into them.
• Optional: a free TMDB API key from themoviedb.org. It gives movies, shows and anime their posters, cast, crew, collections and world ratings.
• Optional: a GPU for hardware video transcoding: Intel or AMD (/dev/dri) or NVIDIA.

If you don't have Docker yet, install Docker Engine on Linux (it includes docker compose) or Docker Desktop on macOS and Windows. Synology, Unraid, TrueNAS and similar systems have Docker in their app centres.

Install With Docker Compose

1. Make a folder for Plinthio, download the compose file into it, and start it:

   mkdir plinthio && cd plinthio
   curl -fsSLO https://raw.githubusercontent.com/OddOmens/Plinthio/main/docker/docker-compose.yml
   MEDIA_DIR=/path/to/your/media docker compose up -d

2. Open http://<your-server-ip>:8088 in a browser.

3. Follow the setup wizard.

Instead of putting settings on the command line, you can keep them in a .env file next to docker-compose.yml:

# The folder holding your media, and your time zone
MEDIA_DIR=/srv/media
TZ=Europe/London
# Owner of ./config (run `id` to see yours)
PUID=1000
PGID=1000
# Which updates to take, see Updating
PLINTHIO_TAG=1

Every variable is listed in Configuration. PLINTHIO_TAG is explained in Updating.

Without Compose

The same thing as a single docker run:

docker run -d --name plinthio --restart unless-stopped \
  -p 8088:8080 \
  -e TZ=Europe/London \
  -v "$PWD/config:/config" \
  -v /path/to/your/media:/media \
  ghcr.io/oddomens/plinthio:latest

This publishes plain HTTP only. To also use Plinthio's built-in HTTPS, add -p 8443:8443.

NAS Docker Apps

On Synology Container Manager, Unraid, TrueNAS or Portainer, create a container from ghcr.io/oddomens/plinthio with the same settings:

• Container port 8080 published on a host port of your choice (the compose file uses 8088). Optionally container port 8443 for HTTPS.
• A folder mapped to /config.
• Your media mapped to /media.
• Optionally TZ, PUID and PGID.

What the Compose File Sets Up

	On the host	In the container
Web app and API	port 8088 (on BIND_ADDRESS, default 0.0.0.0)	port 8080
The same over HTTPS, with Plinthio's own certificate	port 8443	port 8443
Database, settings, covers, caches, backups	./config	/config
Your media	MEDIA_DIR (default /media/library)	/media

WARNING

Publishing a port with Docker usually bypasses the host firewall, so 0.0.0.0 means anyone on your network can reach Plinthio. To make it reachable only from the server itself, set BIND_ADDRESS=127.0.0.1 in .env.

The container also has a health check. docker ps shows it as unhealthy if the server stops answering.

What's in /config

Path	What it is	Safe to delete?
plinthio.sqlite (and -wal, -shm)	The database: users, progress, settings, catalog	No
jwt.secret	The key that signs sign-ins, made on first start	Deleting it signs everyone out and resets everyone's two-factor
ssl/	The local certificate authority and HTTPS certificate	Deleting it makes a new CA, which every device has to install again
.version	The last version that ran, used for the pre-upgrade backup	Yes
backups/	Scheduled, manual and pre-upgrade database backups	Old ones, yes
covers/	Cover art found in folders, fetched from providers or uploaded	It rebuilds, but uploaded covers are lost
avatars/	Profile pictures	Pictures are lost
intro/	Your own opening sequence clip, if you uploaded one	The built-in clip is used again
cache/	Thumbnails, converted video segments, scrub previews, episode stills, rendered PDF pages	Yes, it all regenerates

Files in /config are owned by user and group 1000:1000 by default. Set PUID and PGID to match your host user if needed. If you run the container with a fixed user: (or --user), Plinthio runs as that user and PUID/PGID are ignored.

Several Media Folders

Mount each folder under /media and add each one as a library in the app:

    volumes:
      - ./config:/config
      - /srv/audiobooks:/media/audiobooks
      - /mnt/nas/manga:/media/manga
      - /mnt/nas/video:/media/video

The Setup Wizard

The first visit to a new server opens the setup wizard. It can only be completed from your home network. It has seven steps:

1. Appearance: the server name, light or dark theme, and accent colour.
2. Admin Account: your username and password (at least 8 characters). This account manages libraries, settings and who can use the server.
3. Media Types: which kinds of media appear on the shelf.
4. Libraries: optional. Add folders and give each a type. In Docker, your media is under /media. Each one is scanned straight away. See Libraries.
5. Household: optional. Add more accounts with a username, password and role, and choose whether to Turn on watch parties.
6. Access: where you'll use Plinthio: At home only, At home, and away with Tailscale, or Also from the internet, for guests. The Tailscale choice opens a step-by-step guide. See Away From Home.
7. Review & Finish: check your choices and launch.

When setup finishes, Plinthio offers to turn on two-factor sign-in for your admin account. You can skip this and do it later in Settings → Security.

Large libraries take a while to scan. Titles appear as they're found. Everyone added later goes through a short onboarding the first time they sign in: their theme and which media types they want to see.

Next Steps

• Admin → Metadata: add a TMDB key if the page says none is set. Without one, videos still get titles from file names and covers from folders or video frames.
• Admin → Playback: press Test under hardware acceleration to check it works.
• Admin → Backups: daily backups are on by default. Add a second place to copy them to.
• Admin → Users: add the rest of the household, with content limits or Kids Mode where needed. See Accounts and Access.

Installing the App on Phones and Tablets

Plinthio is a Progressive Web App:

• iPhone and iPad: open it in Safari, then Share → Add to Home Screen.
• Android: open it in Chrome, then Install app.

It opens full screen, shows audiobook controls on the lock screen, and works offline for anything you've downloaded.

Installing as an app and offline downloads need HTTPS (except on localhost). Plain http://192.168… works in the browser but shows a "not secure" warning and can't download for offline use. The ways to get HTTPS are below.

HTTPS

Browsers only trust a certificate from an authority they already know, and no public authority issues one for a home address like 192.168.1.20. You have three options:

• Tailscale (recommended). A trusted https://plinthio.<your-tailnet>.ts.net address at home and away. Devices need the free Tailscale app. No domain, no router changes. See Away From Home.
• A web address for guests. https://media.yourdomain.com with a real certificate, through the Caddy add-on. Needs a domain and two forwarded ports. See Away From Home.
• Plinthio's own certificate. HTTPS on your home network only. Each device installs Plinthio's certificate once (below).

Plain http://<server>:8088 keeps working whichever you choose.

Plinthio's Own Certificate

The Docker image serves HTTPS on port 8443 next to plain HTTP. Its certificate comes from a small certificate authority (CA) that Plinthio creates on first start, in /config/ssl. Install that CA once on each device and the warnings stop, including when the server re-issues its certificate for a new address or before it expires.

1. Open Plinthio on the device over plain http://<server>:8088. The certificate adds that address automatically (a private IP or a .local-style name). To cover an address in advance, set TLS_HOSTNAMES=192.168.1.20,nas.local in .env.
2. Open the in-app docs (Documents in the account menu) → PWA Mobile App Setup and tap Download certificate, or open http://<server>:8088/api/tls/ca.crt. Then:
   • iPhone and iPad: Settings → Profile Downloaded → Install, then Settings → General → About → Certificate Trust Settings → turn on "Plinthio Local CA".
   • Android: Settings → Security → Encryption & credentials → Install a certificate → CA certificate.
   • Mac: open it and set it to Always Trust in Keychain Access.
   • Windows: Install Certificate → Local Machine → Trusted Root Certification Authorities.
   • Firefox keeps its own list: Settings → Certificates → Authorities → Import.
3. Open https://<server>:8443. If you installed the app from the http:// address before, add it to the home screen again from the HTTPS one.

The CA can only sign for private addresses (192.168.x, 10.x, 172.16–31.x, Tailscale's 100.64/10, loopback) and local names (.local, .lan, .home, .internal, .home.arpa, localhost). Even someone who copied its key couldn't use it to impersonate another website.

• A public domain or IP in TLS_HOSTNAMES is only allowed if it's set before the CA is created. To add one later, delete /config/ssl, restart, and install the new CA on each device. This includes a Tailscale .ts.net name. Its 100.x address works without it.
• Up to 16 addresses are learned automatically. After that the log says nothing more will be added. To start over, delete /config/ssl/learned-names.json and restart.
• Your own certificate: put cert.pem and key.pem in /config/ssl, or point TLS_CERT and TLS_KEY at them.
• Turn HTTPS off: set HTTPS_PORT= (empty).

Hardware Transcoding

Most video plays without any conversion (see Movies and Shows). When a file does need converting, a GPU makes it much cheaper. Detection is automatic, and Admin → Playback shows what was found, lets you force a method or turn it off, and has a Test button that runs a real encode.

• Intel QuickSync or AMD (VAAPI): the drivers are in the image. Uncomment the devices: and group_add: lines in docker-compose.yml. The group_add value is your host's render group ID, from getent group render.
• NVIDIA (NVENC): install the NVIDIA Container Toolkit on the host, then uncomment the deploy: block.
• None: leave it all commented. Video still plays, and ffmpeg converts on the CPU.

    devices:
      - /dev/dri:/dev/dri
    group_add:
      - "992"  # host 'render' group GID

With the device lines active, docker compose up refuses to start on a machine without that device. The Intel driver is only in the x86-64 image.

Without Docker

Plinthio also runs directly on a machine. You need:

• Node.js 22 or later (24 recommended).
• ffmpeg and ffprobe for all video. Without them, video that needs converting fails with P303.
• poppler (pdfinfo and pdftoppm) for PDFs. Without it, PDFs fail with P308.
• For Intel hardware transcoding: intel-media-va-driver-non-free and vainfo.

# Debian / Ubuntu
sudo apt install ffmpeg poppler-utils
# macOS
brew install ffmpeg poppler

git clone https://github.com/OddOmens/Plinthio.git && cd Plinthio
cd frontend && npm ci && npm run build && cd ..
cd backend && npm ci
DATA_DIR=/var/lib/plinthio PORT=8088 node src/index.js

The server serves the built web app from frontend/dist. Without Docker, data goes to a data folder inside backend/ unless you set DATA_DIR, and the built-in HTTPS is off unless you set HTTPS_PORT.

Building the Image From Source

To run a build from a checkout instead of a published image:

git clone https://github.com/OddOmens/Plinthio.git && cd Plinthio
docker compose -f docker/docker-compose.yml -f docker/docker-compose.build.yml up -d --build