Docker Installation

The supported, recommended way to run Vynl in production. Works on any Linux/macOS host with Docker, and on most NAS devices.

Tested platforms

Platform	Status	Notes
Linux x86_64	✅	Docker Engine 24+
macOS (Apple Silicon)	✅	Docker Desktop 4.20+
macOS (Intel)	✅	Docker Desktop 4.20+
Raspberry Pi 4/5 (ARM64)	✅	Multi-arch image; allow 2GB RAM headroom
UGREEN NAS (UGOS Pro)	✅	The primary dev/test platform
Synology DSM 7+	✅	Use Container Manager
QNAP Container Station	⚠️	Reported working, not regularly tested
Windows (WSL2)	⚠️	Works but volume-mount paths are awkward

Pulling the image directly (no source needed)

If you don't want to clone the repo, you can pull the published image:

docker pull cand0rian/vynl-app:latest

Or a specific version (recommended for production):

docker pull cand0rian/vynl-app:v0.6.36

The full release list: https://hub.docker.com/r/cand0rian/vynl-app/tags

Minimal docker-compose.yml

services:
  vynl:
    image: cand0rian/vynl-app:latest
    container_name: vynl
    restart: unless-stopped
    ports:
      - "3101:3101"
    volumes:
      - /path/to/your/music:/music:ro       # your library, read-only
      - vynl-data:/app/data                  # DB + persistent state
      - vynl-covers:/app/public/covers       # album art (runtime-added)
      - vynl-artists:/app/public/artists     # artist images
    environment:
      - VYNL_DB_DIR=/app/data
      # - ANTHROPIC_API_KEY=                # optional: set via Settings UI instead
      # - SPOTIFY_CLIENT_ID=
      # - SPOTIFY_CLIENT_SECRET=

volumes:
  vynl-data:
  vynl-covers:
  vynl-artists:

Save this as docker-compose.yml, then:

docker compose up -d
docker compose logs -f vynl     # watch it start

Volume mount notes

• /music:ro — read-only. Vynl never writes to your music folder (this is enforced — see project rule on file deletion). Symlinks inside /music resolve correctly.
• vynl-data — SQLite DB, beets DB, app state. Back this up regularly (see Backup & Restore).
• vynl-covers and vynl-artists — image caches. Survivable loss; Vynl will refetch from MusicBrainz / CAA when missing.

Reverse proxy / HTTPS

Vynl listens on plain HTTP on port 3101 by design. Put a reverse proxy in front for TLS:

• Tailscale Serve — easiest if you're on a tailnet. See Tailscale Setup
• Caddy — single-line config for HTTPS
• Traefik / nginx — standard patterns work

# Caddy example
vynl.your-domain.com {
    reverse_proxy localhost:3101
}

Updating

docker compose pull
docker compose up -d

The on-boot migration in Vynl handles schema changes transparently. Read Updating Vynl before jumping multiple versions (e.g. 0.5.x → 0.6.x).

Resource usage

Typical steady-state on a 15,000-track library:

• CPU: <2% idle, 30–60% during scans
• RAM: ~300MB idle, ~600MB during AI playlist generation
• Disk: ~10MB for DB, ~500MB for cover/artist images (depending on library size)

The container does not pre-allocate; usage scales with library size.

Troubleshooting Docker-specific issues

Symptom	Fix
docker compose up hangs	Check docker logs vynl — usually a permission issue on /music mount
Covers visible at scan but 404 in browser	Resolved in v0.6.33+ via /api/covers/ route. Update if older
Sonos rooms not discovered	Vynl needs network_mode: host for SSDP discovery. See Sonos Setup
ARM build fails to pull	Confirm you're on :latest (multi-arch); avoid version tags older than 0.6.20 on ARM

Next steps

• Configuration — env vars and Settings UI
• Sonos Setup
• Backup & Restore