Single server (systemd)

This is the smallest way to run Playarr: one compiled binary, one SQLite file, one machine. It suits a Raspberry Pi 4/5, a Synology or QNAP NAS, a mini-PC or any always-on Linux box you administer directly. There are no external services to stand up, no database server, no cache, no message broker, and the whole thing survives an unattended reboot because systemd owns it.

Playarr is SQLite-only: DATABASE_URL must be a sqlite: URL, and a postgres:// URL is rejected at startup. The coordinator is in-process and the cache is in-memory. To run more than one server, give each its own database and connect them with peer sync.

Playarr reads a library you already have on disk and reconciles metadata from library managers you already run. It plays what is there; it does not put anything there.

Before you start

FFmpeg is a hard runtime requirement

Playarr shells out to ffprobe to read container durations and stream layouts, and to ffmpeg to extract subtitles into WebVTT and to produce on-demand HLS renditions. Neither binary is bundled with the server binary, and a bare-metal install must supply both.

# Debian, Ubuntu, Raspberry Pi OS
sudo apt-get update && sudo apt-get install -y ffmpeg

# Fedora (RPM Fusion enabled)
sudo dnf install -y ffmpeg

Confirm both are visible on PATH before continuing:

ffmpeg -version
ffprobe -version

If your distribution installs them somewhere unusual, point Playarr at them explicitly with PLAYARR_FFMPEG_BINARY and PLAYARR_FFPROBE_BINARY (both default to a bare ffmpeg / ffprobe resolved on PATH).

Hardware acceleration: not built yet. There is no VAAPI, NVENC, QSV, CUDA or VideoToolbox path anywhere in the server. The on-demand transcode command is built with -c:v libx264, a software encoder, and no unit file, container or manifest in the repository passes through /dev/dri or an NVIDIA runtime. Size your machine for software transcoding, or keep files your devices can already play directly.

1. Obtain the playarr binary

Each Playarr release (a v<version> GitHub Release) carries playarr-server-<version>-linux-amd64.tar.gz and playarr-server-<version>-linux-arm64.tar.gz, each with a .sha256 sidecar. The newest is always at https://playarr.app/downloads/server/playarr-server-linux-amd64.tar.gz (or -arm64), and the container image is ghcr.io/playarrapp/playarr:<version>. There is no hosted one-line installer script; building from source also works.

Build from source

You need a Rust toolchain and a working C linker (build-essential on Debian/Ubuntu, gcc elsewhere). The repository pins the stable channel via rust-toolchain.toml at the repository root, so rustup selects it automatically for any cargo command run inside the tree.

git clone https://github.com/playarr/playarr.git
cd playarr/backend
cargo build --release --bin playarr

backend/Cargo.toml is both the Cargo workspace root and the playarr-bin package, so the binary lands at backend/target/release/playarr. SQLite is compiled into every build, so this one artefact serves every deployment shape.

Or unpack a release tarball, once one exists

The .sha256 sidecar is generated inside the workflow’s own dist/ directory, so the path it records is dist/playarr-…tar.gz and a bare sha256sum -c against it will not find the file. Compare the digests instead:

sha256sum playarr-aarch64-unknown-linux-gnu.tar.gz
cat playarr-aarch64-unknown-linux-gnu.tar.gz.sha256   # same digest, path prefixed with dist/

tar -xzf playarr-aarch64-unknown-linux-gnu.tar.gz    # yields ./playarr

The tarball contains the bare executable. install.sh refuses a source path that is not a regular, executable file, so keep the extracted permission bits (do not, for example, copy it through a filesystem that drops them).

2. Run the installer

infra/systemd/install.sh creates the service user, the directory layout, and installs the unit files. It deliberately does not enable or start anything, that is a separate, explicit decision you make after reviewing the configuration.

sudo ./infra/systemd/install.sh /path/to/playarr

If you place the binary next to install.sh as ./playarr, you can omit the argument.

Re-running the installer is safe: it never overwrites an existing /etc/playarr/playarr.env.

What it creates

It finishes with systemctl daemon-reload and prints the remaining steps.

REDIS_URL is not used. If your installer’s printed summary or your copy of the example file still mentions REDIS_URL, ignore it: it is not read, and nothing needs it.

Playarr’s logging layer writes JSON to stdout, so in practice everything goes to the journal rather than to /var/log/playarr. The directory exists and is writable because the sandbox allowlists it.

3. Configure /etc/playarr/playarr.env

Playarr has no configuration file format at all. There is no config.toml, no YAML, no --config flag. Every setting is an environment variable, read once by playarr-config::Config::from_env at process startup and loaded here via the unit’s EnvironmentFile=.

sudoedit /etc/playarr/playarr.env

The genuine minimum

One line is enough to boot:

DATABASE_URL=sqlite:///var/lib/playarr/playarr.db

For any deployment you intend to keep, add a stable signing secret:

DATABASE_URL=sqlite:///var/lib/playarr/playarr.db
PLAYARR_JWT_SECRET=<64 random hex characters, generate with: openssl rand -hex 32>
PLAYARR_LOG=info
PLAYARR_HTTP_BIND_ADDR=0.0.0.0:8484
PLAYARR_METRICS_BIND_ADDR=0.0.0.0:9090

PLAYARR_JWT_SECRET must be at least 32 bytes; anything shorter is ignored with a warning. If it is unset, Playarr derives a stable secret from its persisted node identity, so sessions survive restarts; set it explicitly anyway.

Corrections to the shipped example file

The seeded /etc/playarr/playarr.env is a copy of infra/systemd/playarr.env.example, which may still carry leftovers from the removed Postgres support. Fix these before you start the service.

DATABASE_URL may be blank. Set it to the sqlite: URL above. A postgres:// value is rejected at startup.

GOOGLE_APPLICATION_CREDENTIALS and PLAYARR_FIREBASE_WEB_CONFIG are uncommented and will stop the service booting. The first points at /etc/playarr/firebase-service-account.json, a file the installer does not create; the server reads it eagerly and fails startup if it is missing. The second is set to an empty string, which is parsed as JSON and fails. Comment out both lines unless you are actually configuring Firebase messaging, which is entirely optional and not needed for a first install.

Configuration reference

These are the variables that matter on a single server. Every one is read at startup only, there is no hot reload.

Where state lives on disk

Everything Playarr owns sits under /var/lib/playarr, which is the unit’s WorkingDirectory and one of only two paths the sandbox permits it to write to.

The database file is created on first connect, ?mode=rwc is appended automatically to any sqlite: URL that does not already specify a mode. The pool then sets PRAGMA journal_mode = WAL and PRAGMA busy_timeout = 30000. Schema migrations are embedded in the binary and applied automatically at every startup.

The artwork cache path is derived from the database file’s parent directory when DATABASE_URL begins sqlite://. If you move the database elsewhere, set PLAYARR_ARTWORK_CACHE_DIR explicitly so the cache follows it.

The transcode output root is not configurable by any environment variable. Because the unit sets PrivateTmp=true, it lands in a private /tmp; on distributions where /tmp is a tmpfs, that space is RAM-backed. Keep an eye on it if you expect several concurrent transcode sessions.

4. The unit file

This is /etc/systemd/system/playarr.service, installed verbatim from infra/systemd/playarr.service. Long explanatory comments have been abridged here; the installed file keeps them.

[Unit]
Description=Playarr media automation service
Documentation=https://github.com/playarr/playarr
After=network-online.target
Wants=network-online.target
StartLimitIntervalSec=300
StartLimitBurst=5

[Service]
Type=simple
User=playarr
Group=playarr

EnvironmentFile=-/etc/playarr/playarr.env

Environment=PLAYARR_ROLE=all

ExecStart=/usr/local/bin/playarr
WorkingDirectory=/var/lib/playarr

Restart=on-failure
RestartSec=5

TimeoutStopSec=30

# --- Sandboxing / hardening ---
NoNewPrivileges=true
AmbientCapabilities=CAP_NET_BIND_SERVICE
CapabilityBoundingSet=CAP_NET_BIND_SERVICE
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
ReadWritePaths=/var/lib/playarr /var/log/playarr
UMask=0027

[Install]
WantedBy=multi-user.target

What each of the load-bearing directives is doing:

If your copy of the unit’s header carries a commented-out After= line naming a database or cache service, leave it commented.

The commit that added these units notes they were authored on a machine without systemd and have not been checked with systemd-analyze verify. Run systemd-analyze verify playarr.service after installing if you want that confirmation on your own host.

5. Enable and start

sudo systemctl enable --now playarr.service

enable wires it to multi-user.target so it comes back after a reboot; --now starts it immediately.

6. Retrieve the bootstrap admin credentials

On the very first boot against an empty database, Playarr provisions exactly one administrator before it serves any traffic. If you did not set PLAYARR_BOOTSTRAP_ADMIN_PASSWORD, a random 64-character password is generated, hashed with Argon2id for storage, and written to the journal once, at WARN:

journalctl -u playarr.service | grep 'bootstrap admin'

Save it now, it is not shown again. If any user already exists, this step is a no-op.

The bootstrap admin is granted is_admin but deliberately not can_stream. It exists to operate Playarr’s admin surface, not to watch things. Create a separate account for yourself as a viewer.

Authentication defaults to full-account, meaning every sign-in needs a real username and password. The trusted-network mode is opt-in and auto-signs-in any request from an allowlisted private range as the default admin, convenient on a trusted LAN, unsuitable anywhere else.

7. Check it is healthy

systemctl status playarr.service

Then hit the endpoints directly. /healthz is liveness, /readyz flips to 200 only once migrations have applied and the listener is genuinely serving, and the version envelope needs no authentication:

curl -fsS http://127.0.0.1:8484/healthz
curl -fsS http://127.0.0.1:8484/readyz
curl -fsS http://127.0.0.1:8484/api/system/version

Metrics are served on their own port, by every role, unconditionally:

curl -fsS http://127.0.0.1:9090/metrics | head

A healthy first boot emits, roughly in this order: starting playarr carrying the resolved role; metrics listener listening on the metrics address; the bootstrap admin WARN (first boot only); and finally http server listening, or https server listening with static certificate, on the application address. Migrations, and the creation of the two default library views (“Newly Added” and “Newly Released”), are both silent when they succeed and only log if they fail, so their absence from the journal is the expected case rather than a problem.

Logs

Playarr logs structured JSON to stdout, so systemd captures everything in the journal.

journalctl -u playarr.service -f            # follow
journalctl -u playarr.service -n 200        # last 200 lines
journalctl -u playarr.service --since today

Raise verbosity per module with PLAYARR_LOG, then restart:

PLAYARR_LOG=info,playarr_api=debug,playarr_arr_sync=debug

Configuration is read once at startup, so every change to /etc/playarr/playarr.env needs:

sudo systemctl restart playarr.service

Optional: HTTPS

Three transport modes are mutually exclusive and chosen at startup.

Setting both a static certificate and an ACME domain is a hard startup error, as is setting only one of the two TLS paths.

# Static certificate. The key must be readable by the playarr group.
PLAYARR_TLS_CERT_PATH=/etc/playarr/tls/fullchain.pem
PLAYARR_TLS_KEY_PATH=/etc/playarr/tls/privkey.pem

# Automatic HTTPS. PLAYARR_ACME_ENVIRONMENT is mandatory and must be
# exactly "production" or "staging", so a staging certificate can never be
# mistaken for a browser-trusted one. ACCEPT_TERMS must be the literal "true".
PLAYARR_ACME_DOMAIN=<YOUR-PUBLIC-HOSTNAME>
PLAYARR_ACME_ENVIRONMENT=production
PLAYARR_ACME_ACCEPT_TERMS=true
PLAYARR_ACME_CONTACT=<YOU>@example.com
PLAYARR_ACME_CACHE_DIR=/var/lib/playarr/acme
PLAYARR_ACME_HTTP01_BIND_ADDR=0.0.0.0:80

In ACME mode Playarr runs its own HTTP-01 challenge listener, 308-redirects plain HTTP arriving there to the HTTPS origin, persists account and certificate state under the cache directory, and renews without a restart. If no certificate is issued within 120 seconds of startup the process exits with an error.

If you prefer your own proxy, leave both sets unset and reverse-proxy to 127.0.0.1:8484. Never proxy port 9090 to the public edge.

Optional: co-host Playarr Admin

Playarr Admin is the operator-facing React UI, served by the same binary at / on the same origin and port as the API, the same pattern the library managers use. If no index.html is found at the resolved path, the server serves the API only and logs an informational line saying so. Nothing is installed for you: install.sh copies the binary and the units and nothing else.

Building it needs Node 20 or newer and pnpm 9 or newer; the workspace pins pnpm through Corepack. From a checkout of the repository:

corepack enable && corepack prepare pnpm@11.13.0 --activate
cd /path/to/playarr/clients/tv-web
pnpm install --frozen-lockfile
pnpm --filter @playarr-tv/admin... run build

The trailing ... on the filter matters. @playarr-tv/admin imports three workspace packages (@playarr-tv/api-client, @playarr-tv/device-auth, @playarr-tv/domain) whose main/exports point at their own dist/ output, so the build fails on a fresh checkout without it. Do not substitute pnpm -r run build, that also drives the TV app shells’ packaging steps, which need ares-package and the Tizen Studio CLI.

Copy the result into a directory the sandbox can read, then point the server at it:

sudo install -d -o playarr -g playarr -m 0750 /var/lib/playarr/web
sudo cp -r admin/dist/. /var/lib/playarr/web/
sudo chown -R playarr:playarr /var/lib/playarr/web

# in /etc/playarr/playarr.env, the shipped example file already sets
# this exact line, so on a seeded install there is usually nothing to add.
PLAYARR_WEB_ASSETS_DIR=/var/lib/playarr/web

sudo systemctl restart playarr.service

Playarr, the viewing client, is a separate application, and install.sh never installs or serves it. The official container image also reserves this slot for Playarr Admin; Playarr Web is hosted independently at its public origins.

Updating and backing up

Upgrading is manual. Replace the binary and restart; the embedded migrations run on the next start.

sudo install -o root -g root -m 0755 /path/to/new/playarr /usr/local/bin/playarr
sudo systemctl restart playarr.service

Self-update is not built yet. playarr-update-check.timer ships installed but disabled, and enabling it is one explicit systemctl enable --now playarr-update-check.timer. Even then, playarr update --check makes no network call today and unconditionally reports the running binary as current, and playarr update --yes returns “not implemented yet” and touches no files. The signed-download-and-atomic-swap sequence exists only as a doc comment describing intended future work. Treat both as inert.

Backups. Playarr has a built-in, opt-in backup feature that writes age-encrypted archives to PLAYARR_BACKUP_DIR (see Upgrade and backup); the shipped unit and example env file do not enable it, and it keeps no off-node copy unless you copy archives away or configure an S3-compatible destination. Otherwise, on this tier the state that matters is a single directory, which you can archive cold:

sudo systemctl stop playarr.service
sudo tar -czf playarr-backup-$(date +%F).tar.gz -C /var/lib playarr
sudo systemctl start playarr.service

Stopping the service first is the simple way to get a consistent copy of a WAL-mode SQLite database along with its -wal and -shm companions. Keep /etc/playarr/playarr.env somewhere safe too, losing PLAYARR_JWT_SECRET signs out every device.

More than one server. Run a second server with its own SQLite database and connect the two with peer sync. There is no shared database to scale out to.

Next

The service is running, the database exists, and you have admin credentials. Continue to First run to sign in, register the library-manager instances Playarr should reconcile metadata from, and connect your first Playarr client.