Playr

Your music. Your library. Your server.

A self-hosted music, audiobook, recording and video library with playlists, cover art, ratings, profile filters, background playback and offline downloads. Run it on your own computer or a Hetzner VPS. Source code is included under the MIT license. Hosting and optional third-party services have their own costs.

Hosting credit

Get the official €50 Hetzner new-customer credit. Redeem within 14 days of account creation; credit expires at the end of that billing month. Check the live eligibility terms. This is a public promotion, not an affiliate link.

Give this to your LLM

Download and extract the ZIP, open its Playr folder in your coding assistant, and paste:

Read LLM-SETUP.md and SETUP.md. Interview me about where I want Playr to run, how many people will use it, profile names, passwords, how many administrators and listeners I need, remote access, domain, storage and backups. Explain the supported access model before configuring anything. Then install it with fresh credentials, verify playback and persistence, and give me operating instructions. Ask before billable resources or opening my home network to the internet. Never publish my secrets.

The ZIP contains the full tutorial (SETUP.md), the LLM configuration interview (LLM-SETUP.md), source, database migrations, a setup wizard, Docker and Compose files, a Caddy HTTPS configuration, authentication tests and a release packager. You can also download the tutorial and interview separately from this page.

Choose your setup

• Local personal player: default binds only to localhost. No account with a hosting provider or router changes needed.
• VPS without a domain: use a private SSH tunnel. No public web ports required.
• LAN / private VPN: explicitly configure the trusted devices and firewall; password recommended.
• Public VPS or home hosting: domain, password, HTTPS, firewall and backups. The guide covers DNS, router forwarding, CGNAT and external verification.

Access model — read before sharing

Playr 1.0 uses a shared site password. Everyone admitted can manage the library through the API. Profiles and profile passwords are convenience controls, not isolated accounts or server-enforced permissions. The upload URL parameter reveals controls; it is not an administrator credential.

If you need separate administrators/listeners or private per-user libraries, ask your LLM to implement and test real account and permission checks before deployment. The interview and wizard explicitly flag that limitation. Open mode gives visitors full management access and is intended for a personal loopback-only installation.

Local quick start

Install Node.js 24 LTS and Docker Desktop (Windows/macOS), or Docker Engine with the Compose plugin (Linux). Start Docker. In the extracted Playr folder:

npm run setup
docker compose up -d --build
docker compose ps

The wizard uses Node built-ins and does not need npm dependencies installed. It generates independent random database, site-password and token-signing credentials in your private .env. It refuses to overwrite existing configuration. Read PASSCODE locally, then open http://localhost:3000. Do not paste .env into a chat.

Leave domain blank for local HTTP; COOKIE_SECURE=false is appropriate only for local HTTP or a private SSH tunnel. The public configuration enforces password mode and secure cookies. After startup, add profiles through /?upload=1, or run npm run setup:profiles for the profile names recorded by the wizard.

Hetzner deployment

Start with Hetzner’s official €50 new-customer promotion. The offer is €50 in credit, not US $50. Copy the current code from that page, create your account, then redeem it under User Account → Promo Codes within 14 days of account creation. Credit expires at the end of the billing month in which it is redeemed, rather than 30 days later. Check the live terms and confirm the credit in your account before relying on it. Normal charges apply beyond the credit or after expiry. This is a public promotion, not a personal affiliate link. If ineligible, use Hetzner Cloud normally.

1. Sign into your own Hetzner account, complete any verification, enable MFA and create a Playr project.
2. Generate an SSH key locally with ssh-keygen -t ed25519. Keep the private key on your machine; add only its .pub public key to Hetzner.
3. Review current server, IPv4, storage, backup and traffic pricing with your LLM before creating billable resources. A practical starting size is 2 vCPU and 4 GB RAM with enough disk for builds and your library; large libraries need more storage.
4. Create an Ubuntu 24.04 LTS server in your preferred region with that public SSH key. Attach a Cloud Firewall: TCP 22 only from your admin IP; TCP 80/443 for a public website. Leave 3000/5432 closed. The private SSH-tunnel route needs only 22.
5. Connect over SSH, verify its fingerprint, apply OS updates, create a normal sudo administrator and verify a second key-based session before restricting SSH. Install Docker Engine and Compose using Docker's official Ubuntu repository. SETUP.md includes the exact repository and install commands.
6. Transfer only this downloaded release ZIP, extract into a private application directory, then run the setup wizard on the server. Node 24 can be installed on the host, or use the one-off Node container command in SETUP.md. Choose vps, password, profile names and your domain (or leave domain blank for private access). No Hetzner API token is needed when using its Console.
7. At your DNS provider, add an A record for your chosen hostname pointing to the VPS IPv4. Add AAAA only if IPv6 is configured. Remove stale records. Verify DNS from your own machine. Store the hostname in DOMAIN and use COOKIE_SECURE=true for HTTPS.
8. With ports 80/443 available, launch:

docker compose -f compose.yaml -f compose.public.yaml up -d --build
docker compose -f compose.yaml -f compose.public.yaml ps
docker compose -f compose.yaml -f compose.public.yaml logs --tail 80 proxy app

Caddy obtains and renews the certificate automatically when DNS and firewall rules are correct. Check https://YOUR_HOSTNAME/api/health and open the site from another network. Verify the certificate and login using your generated password. Keep using both Compose files for public updates and restarts. Do not stop an existing web server on a shared host; have your LLM allocate a new loopback port and integrate the existing proxy while preserving other sites.

No domain? Use an SSH tunnel

Start only the base Compose stack on the VPS, with COOKIE_SECURE=false. On your local machine run:

ssh -N -L 3000:127.0.0.1:3000 YOUR_ADMIN@SERVER_IP

Keep that connection open and browse http://localhost:3000. Traffic travels through SSH, with no public web port.

Home hosting

The default setup does not open your router. For public hosting, your LLM must ask for consent, check ISP/CGNAT, reserve the machine's LAN IP, configure the domain/dynamic DNS and forward only TCP 80/443 to the HTTPS proxy. Never expose PostgreSQL, Docker or port 3000 publicly. Test on cellular data. If CGNAT prevents forwarding, use a private VPN or VPS. A sleeping home machine is unavailable.

Credentials and optional services

There are no supplied working credentials. PASSCODE, AUTHSECRET and POSTGRESPASSWORD are independently generated per installation. DATABASEURL is set internally by Compose. AUTHVERSION revokes online sessions when incremented. Changing an existing database password requires updating the PostgreSQL role as well as the environment; see the tutorial.

Uploads and playback require no external API subscription. Optional link conversion uses your own RapidAPI account, subscription and server-side RAPIDAPI_KEY; source URLs are sent to that provider. Leave it empty for upload-only use. SSH, hosting and DNS credentials belong to the installing user and never go into frontend code. The optional local music-grab helper requires the user's own server URL and password. Use media you have rights to store.

Media is stored outside the public web directory and served through authenticated API routes. Docker persists the database and media in separate volumes. Default limits are 15 GiB total and 2,000 MiB per file. Browser offline downloads are device-specific and may be evicted; server revocation cannot erase already-downloaded offline media.

Backups, updates and verification

Back up the database, media and private .env together. SETUP.md supplies coordinated backup and separate-project restore commands, plus update and rollback instructions. Keep encrypted off-server copies and test a restore. Do not assume provider snapshots cover attached volumes. Never use docker compose down -v for a normal stop: it deletes data.

Before calling setup complete, your LLM should verify health, reject unauthenticated API/media access in password mode, sign in, upload owned audio, play and seek, create a playlist, restart containers and replay. Test offline playback if wanted. For public hosting verify HTTPS externally and that ports 3000/5432 are closed. Report what was actually tested. A local build alone is not proof of a VPS deployment.

The full operating tutorial and detailed interview are in the download. Review the source before running it; Forge hosts files, it does not operate your server.