Playarr Server.

Before you install

System requirements

1. 64-bit Linux

   x86-64 or ARM64. Docker is optional; the container image is built for both architectures. The server stores its SQLite database and artwork cache in a writable data directory, so it needs persistent storage.

2. ffmpeg and ffprobe

   Required for thumbnails, track probing and on-demand transcoding. The Docker image includes them. On systemd or Kubernetes installs without that image, install ffmpeg (which provides ffprobe) on the host and make sure both are on the server's PATH.

3. Your media apps

   Playarr Server reads from the library sources that you already run. Register each one through the server's admin API after it starts.

4. Network port 8484

   The API listens on TCP 8484, plain HTTP by default. Clients on the same network can connect to it directly. Metrics are on 9090 and should stay on your private network.

Supported install methods

Choose one

Pick one. Each method runs the same single all-in-one server process. The Docker commands pull the public image; the other methods use the downloaded tarball or your own chart values.

1. Docker

   Pulls the multi-arch image, ffmpeg included, and starts one container with SQLite state in a named volume. The generated PLAYARR_JWT_SECRET keeps sessions across restarts; save it if you recreate the container.

   • docker pull ghcr.io/playarrapp/playarr:latest
   • docker run -d --name playarr --restart unless-stopped -p 8484:8484 -v playarr-data:/data -e DATABASE_URL=sqlite:///data/playarr.db -e PLAYARR_JWT_SECRET="$(openssl rand -hex 32)" ghcr.io/playarrapp/playarr:latest
   • curl http://localhost:8484/healthz

2. Docker Compose

   The same image as a compose file. Replace the secret with a long random string, then start it and open port 8484.

   • services: playarr: image: ghcr.io/playarrapp/playarr:latest container_name: playarr restart: unless-stopped ports: - "8484:8484" environment: DATABASE_URL: sqlite:///data/playarr.db PLAYARR_JWT_SECRET: change-me-to-a-long-random-string volumes: - playarr-data:/data volumes: playarr-data:
   • docker compose up -d

3. systemd on a Linux host

   Unpack the tarball, then install.sh installs the playarr-server binary, the Admin UI, an unprivileged playarr user and the unit files. It does not enable or start anything until you do. Set DATABASE_URL in the env file first, for example sqlite:///var/lib/playarr/playarr.db.

   • tar -xzf playarr-server-linux-amd64.tar.gz
   • cd playarr-server-*-linux-amd64
   • sudo ./systemd/install.sh
   • sudoedit /etc/playarr/playarr.env
   • sudo systemctl enable --now playarr.service
   • journalctl -u playarr.service -f

4. Kubernetes (Helm chart)

   The playarr-standalone chart runs one Pod with a Recreate strategy for a single SQLite-backed server. Point it at the public image, an existing Secret and persistent storage. The chart never creates Secrets and has no migration or deletion hooks. Render and review it before applying.

   • # set image.repository to ghcr.io/playarrapp/playarr and image.tag to a release version
   • helm template playarr infra/kubernetes/helm/playarr-standalone --values my-values.yaml

Connect your clients

HTTPS and the playarr.app relay

Native apps can connect to the server's address on your network. The hosted web client at playarr.app is served over HTTPS, so it needs a browser-trusted certificate for the server. Bring your own, or use the optional relay.

Optional relay (off by default)

For a server with a public IPv4 address and TCP 8484 reachable from the internet. The server registers with playarr.app, which publishes a DNS-only name such as v4-203-0-113-10.relay.playarr.app pointing at your address. The server then obtains its own Let's Encrypt certificate over DNS-01, so port 80 is not needed. For a short period after start, typically under two minutes, the API is plain HTTP; it then switches to HTTPS on the same port.

• PLAYARR_RELAY_REGISTER=true
• PLAYARR_ACME_CHALLENGE=relay-dns-01
• PLAYARR_ACME_DOMAIN=v4-<A>-<B>-<C>-<D>.relay.playarr.app
• PLAYARR_ACME_ACCEPT_TERMS=true

What the relay shares

Your address, not your media.

Enabling the relay sends your public IPv4 address and a key fingerprint to playarr.app, and the name is public DNS data. No streaming or API traffic passes through Cloudflare. Registration proves control of the address, not who owns the server. Leave it off if you would rather use your own certificate and name.