SetupGetting Started

Getting Started

5 MIN READLast updated: todayv0.6.36

Vynl is a self-hosted music platform. This page gets you from zero to playing music in about 5 minutes.

Before you start

You need one of:

Docker (recommended) — runs on macOS, Linux, Raspberry Pi 4+, NAS devices that support Docker (UGREEN, Synology DSM 7+, QNAP)
Node.js 20+ — if you want to run from source

You also need:

A music library — any folder of audio files. Vynl supports MP3, FLAC, M4A, AAC, OGG, Opus, WAV, WMA, AIFF
(Optional) An Anthropic API key — only if you want AI-generated playlists and Library Doctor features. Vynl works fine without it; AI features just stay greyed out

The 60-second install

git clone https://github.com/48Nauts-Operator/vynl-app.git
cd vynl-app
cp .env.example .env
docker compose up -d

Open http://localhost:3101 and you'll see the Vynl interface.

First-run setup

When you load Vynl for the first time, the library is empty. Do these three things in order:

1. Point Vynl at your music

In docker-compose.yml, edit the volumes: section so /music inside the container maps to wherever your music actually lives:

services:
  vynl:
    volumes:
      - /path/to/your/music:/music:ro       # ← change this
      - vynl-data:/app/data
      - vynl-covers:/app/public/covers
      - vynl-artists:/app/public/artists

Recreate the container after editing:

docker compose up -d

2. Import your library

In the Vynl UI:

Go to Settings → File Watcher (or Settings → Library → Scan)
Click Scan Library
Wait. A library of ~10,000 tracks takes ~5 minutes to scan, ~30 minutes for full metadata enrichment

Or if you already use beets, point Vynl at your beets DB:

Settings → Beets Integration → enter the path to library.db (typically /music/.beets/library.db or ~/.config/beets/library.db)
Click Sync from Beets

This is much faster than a fresh scan because beets has already done the metadata work.

3. (Optional) Add your API keys

For AI features (Discovery, Library Doctor, Genre Normalize):

Settings → API Keys → Anthropic API Key → paste your key from console.anthropic.com → Save

For Spotify migration (one-time, then disconnect):

Settings → API Keys → fill in Spotify Client ID and Spotify Client Secret from a Spotify Developer app → Save
Go to Spotify Migration in the sidebar to import your playlists

Verify the install worked

After scanning, you should see:

Stats page shows your track count
Albums page shows album covers (or the Vynl dragon as a default)
Library → Doctor → Health Check runs without errors

If any of those fail, see Troubleshooting.

Next steps

Sonos Setup — play music on your existing speakers
AI Discovery — natural-language playlist generation
Spotify Migration — bring your playlists across
Configuration — every env var, explained

Docker Installation