Skip to content

Add musicbrainz role for self-hosted MetaBrainz mirror

jedmund requested to merge jedmund/musicbrainz into main

Created by: jedmund

Summary

Add a musicbrainz role that runs the official metabrainz/musicbrainz-docker upstream stack with a thin local/ overlay (Traefik labels, network attachment, replication token). Wire multi-scrobbler in media_consumption to hit the local mirror over shared-network instead of the public musicbrainz.org endpoint.

Why

Multi-scrobbler enriches scrobbles with MusicBrainz metadata. Against the public WS/2 endpoint that's bound by a 1 req/s rate limit and ~600ms round trip, which causes the enrichment queue to back up. Local mirror is rate-limit-free and ~10ms.

Commits

  1. musicbrainz: add role for self-hosted MetaBrainz mirror — the role itself + deploy playbook
  2. infra: wire musicbrainz into orchestration — host group, all.yml import, TinyAuth label
  3. media_consumption: route multi-scrobbler MB lookups to local mirror — defaults var + multi-scrobbler config
  4. Makefile: add deploy-musicbrainz target

Notes

  • Pinned to upstream tag v-2026-04-27.0. Master HEAD references base images that haven't been pushed yet (e.g. metabrainz/musicbrainz-docker-musicbrainz:<tag>-build0 404s on build).
  • DB credentials are upstream defaults (musicbrainz/musicbrainz). Postgres is on an internal-only docker network, never reachable from host or other stacks.
  • No backup strategy — DB is reproducible from upstream dumps. If the volume is lost, re-run the import.
  • Vault key musicbrainz_replication_token must be present in group_vars/musicbrainz/vault.yml before deploy. Get one from metabrainz.org/account/applications.

Test plan

  • group_vars/musicbrainz/vault.yml exists with musicbrainz_replication_token
  • make deploy-musicbrainz brings the stack up cleanly
  • Run the manual import from roles/musicbrainz/README.md (~3-6 hours, do via tmux on nuc-mini)
  • After import: curl -fsS 'http://nuc-mini:5000/ws/2/recording/?query=artist:cornelius&fmt=json' | jq '.count' returns > 0
  • https://musicbrainz.atelier.house resolves and serves the MB UI behind TinyAuth
  • make deploy-media-consumption rolls multi-scrobbler with the new config
  • docker logs multi-scrobbler shows MB lookups hitting http://musicbrainz:5000 and not the public endpoint

Merge request reports