Install · Self-host

Get Vynl running on your box.

Drop the compose file on a Mac mini, NAS, or Linux host. Mount your music read-only, start the container, and open Vynl in your browser. Run Vynl beside your music, not instead of it.

Linux · x86_64Linux · ARM64macOS · Apple SiliconSynology · QNAP · UnraidRaspberry Pi 4+

Pick your platform

The compose, tuned per OS.

The Vynl image is the same on every platform. Network mode, volume paths, and a couple of Docker-specific notes are not — that's what the three tabs handle.

Linux gets the easy path. macOS has one gotcha.

On Linux, network_mode: host gives Vynl direct access to your LAN — Sonos and AirPlay discovery just work. On macOS, Docker Desktop's host networking is limited; if Sonos doesn't show up, switch to ports: ["3101:3101"] and read the discovery notes in About Docker.

docker-compose.linux-mac.yml · latest

Download .yml

services:
  vynl:
    image: cand0rian/vynl-app:latest
    container_name: vynl
    restart: unless-stopped
    # Linux: full host networking. macOS Docker Desktop has limited host networking — see "About Docker" below.
    network_mode: host
    volumes:
      # Linux example: - /srv/music:/music
      # macOS example: - /Users/you/Music:/music
      - /srv/music:/music                # change to your Music path
      - vynl-data:/app/data              # Vynl state (SQLite + AI cache)
      - vynl-covers:/app/public/covers   # cover-art cache
      - ./beets-config.yaml:/home/vynl/.config/beets/config.yaml:ro

    environment:
      - DOCKERHUB_IMAGE=cand0rian/vynl-app
      - MUSIC_LIBRARY_PATH=/music/library
      - BEETS_DB_PATH=/music/library.db
      - VYNL_DB_DIR=/app/data
      - PODCAST_STORAGE_PATH=/music/podcasts
      - VYNL_HOST=http://<YOUR_IP_HERE>:3101
      - NEXT_PUBLIC_VYNL_HOST=http://<YOUR_IP_HERE>:3101
      # Optional: uncomment and fill in for Spotify/AI features
      # - ANTHROPIC_API_KEY=
      # - SPOTIFY_CLIENT_ID=
      # - SPOTIFY_CLIENT_SECRET=
      # - SPOTIFY_REDIRECT_URI=http://<YOUR_IP_HERE>:3101/api/spotify/callback

volumes:
  vynl-data:
  vynl-covers:

→ then:$ docker compose up -d→ open http://<YOUR_IP>:3101

Up in ~90 sec

Replace <YOUR_IP_HERE> (or <YOUR_NAS_IP>) with your LAN IP — e.g. 192.168.1.42. Localhost won't work for Sonos discovery.

First time with Docker? Read the basics ↓

About Docker

First time with Docker?

Docker is how Vynl ships a working stack — Node, FFmpeg, Beets, the AI engine, the web UI — as one immutable image you pull and run. Everything below applies to every platform tab above.

What the image is

One published image at cand0rian/vynl-app. Pull :latest to track the current release, or pin to a tag like :0.6.36 for reproducibility.

Volumes you mount

/music — your library, mounted from the host (read-only is fine)
/app/data — Vynl's SQLite, AI cache, listening history
/app/public/covers — cover-art cache (small, frequently written)
beets-config.yaml — your Beets config, mounted read-only

Networking choices

Host networking (Linux, NAS) gives Vynl direct LAN access — Sonos and AirPlay discover the container as if it were a host process. Port mapping (Mac, Windows) exposes only port 3101; discovery often needs an extra mDNS relay or running Sonos/AirPlay devices on the same subnet as the host.

Day-two commands

# start

$ docker compose up -d

# stop

$ docker compose down

# update to latest

$ docker compose pull && docker compose up -d

# tail logs

$ docker compose logs -f vynl

Don't have Docker yet?

macOS

Docker Desktop — easiest path. Includes Compose v2 by default.

Linux

Install Docker Engine from your distro's package manager, or use the official convenience script.

Windows

Docker Desktop with the WSL2 backend. Enable WSL integration for your distro.

NAS

Synology Container Manager · UGREEN Container Engine · QNAP Container Station · Unraid Community Apps.

Common pitfalls

File permissions: Make sure the user running Docker can read your music directory. On Linux this usually means matching UID/GID; on NAS, the shared-folder permissions UI.
Sonos discovery on Mac/Windows: If speakers don't appear, install an mDNS relay (e.g. avahi-publish) or use a thin Linux VM/host with network_mode: host.
Beets DB path mismatch: If you already have a Beets library with absolute host paths, use BEETS_PATH_REMAP to translate them to the container's mount points.
Updating: Pull the new image and recreate — your data and covers volumes persist across container recreations.

Full configuration reference

What's in the container

One image. A whole stack.

No spelunking through a dozen repos. The Vynl image bundles every component, pinned and tested together.

Beets

v1.6+

Library auto-import, tagging, dedupe, cover art.

Claude AI

Optional

Taste profiles, AI playlists, discovery sessions.

FFmpeg

v6.1

Decode 9 formats. Transcode to AAC for mobile.

SQLite + Beets DB

Local

Library state lives next to your music. No external DB to run.

Sonos controller

SoCo

Discovery, grouping, volume per room.

Tailscale (host)

Optional

Encrypted remote access via host networking. Install on the host, not in the container.

Environment variables

Every flag, explained.

The compose above includes the full set. Here's what each one does, whether you need it, and where to put your own values.

Variable

Status

MUSIC_LIBRARY_PATHWhere the container looks for your music library (inside the container path).

required

BEETS_DB_PATHPath to the Beets SQLite library DB. Sits next to your library.

required

BEETS_PATH_REMAPMap external paths used by an existing Beets DB to the container's mount points. Semicolon-separated pairs in the form host::container.

optional

VYNL_DB_DIRWhere Vynl writes its own state — listening history, AI cache, playlist data.

required

PODCAST_STORAGE_PATHWhere downloaded podcast episodes are stored.

optional

VYNL_HOSTPublic-facing URL Vynl uses internally (e.g. http://192.168.1.10:3101). Needed for Sonos handoff.

required

NEXT_PUBLIC_VYNL_HOSTSame URL, exposed to the web client. Replace <YOUR_IP_HERE> with your LAN IP.

required

ANTHROPIC_API_KEYEnables AI Discovery, taste profile, and Library Doctor. Vynl works fine without it; AI features stay disabled.

optional

SPOTIFY_CLIENT_ID / SECRETRequired only for one-time Spotify playlist migration. Disconnect after import if you want.

optional

DOCKERHUB_IMAGESource image identifier — used by the in-app updater to check for newer builds.

optional

Full reference: Configuration.

System requirements

Anything from a Pi to a NAS

CPU

x86_64 · ARM64

Pi 4 / 5, Intel, Apple Silicon

RAM

512 MB min

2 GB recommended for AI

Disk

200 MB + your library

Container + SQLite + Beets DB

Docker

24.0+ · compose v2

Or Podman 4.6+

NAS users: Synology DSM 7+ and UGREEN run Vynl natively via Container Manager. QNAP and Unraid have Docker installed by default. Recommend SSD for the Beets database; HDD for the music library is fine.

Verify the image (optional)

Signed and reproducible.

Every release tag is signed with cosign and published to GHCR with a transparent supply-chain log. You don't have to verify, but the option is there.

$ cosign verify cand0rian/vynl-app:latest \

--certificate-identity-regexp '.*48Nauts-Operator/.*'

✓ Verified signature · subject: vynl-release-bot

SBOM availableRekor logReproducible build

Once it's running

Four things to do next.

STEP 01

Point at your music

Change the /volume1/Music paths to your real library.

STEP 02

Set your host IP

Replace <YOUR_IP_HERE> so Sonos can reach the container.

STEP 03

Run a discovery session

Drop in an Anthropic API key, rate a few tracks, build a taste profile.

STEP 04

Pair your Sonos

Auto-discovery picks up every speaker on the LAN — group them in the web UI.

Need to go deeper?

The install guide on this site walks through every step. The GitHub repo holds the source, the issue tracker, and the place to ask the maintainer questions directly.

Read the install guide Open the GitHub repo