Minstrel is now a viewer of the library it is pointed at. Finding, downloading and filing music moves out of it. Removed from the server: - the request flow (requests, approval, auto-approve) and the wanted list, follows, release profiles and release blocks; - searching indexers, the download clients, the importer, the album lifecycle and missing-file re-acquisition; - the catalogue's discography, search and art (the MusicBrainz release and track-list cache stays, for the duplicate resolver); - Discover: its suggestions of artists not in the library, snoozes, the candidate-artist tag enrichment and its tuning scope; - writes to acquisition tables from moving the library folder and from merging duplicates, the want-list join on Suspect sources, the sealing of acquisition credentials, and the release-group lookup only re-acquisition used. Settling a wrong-slot duplicate no longer sets the release aside: the copies go and their slots show as missing until a good copy is in the library. Removed from the web: Admin > Acquisition and Requests, /requests, /discover, Follow on the artist page, the auto-approve toggle, and the Collection's wanted-list tabs. The Collection is now the library's health: an overview, Reports, Duplicates, Suspect sources and Missing files. The README and docs no longer describe getting music. The tables stay for now; a later migration drops them. The request notification kinds and the Android screens are still to go. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
7.0 KiB
Hosting Minstrel
Minstrel serves plain HTTP on port 4533 and never terminates TLS itself. On a home network or a VPN you trust, that is all you need. Once the server is reachable from the internet, put it behind a reverse proxy that speaks HTTPS, and tell Minstrel about that proxy. This page covers both.
On a LAN or VPN
Publish the port to the network and use http://<host>:4533:
ports: ['4533:4533']
If nothing sits in front of Minstrel, set Admin › Email & network → Client IP detection to 0. It defaults to 1, which assumes one proxy (see below for why that matters).
On the internet
Three things, all required:
-
Don't publish 4533 to the world. Bind it to the loopback interface so only the proxy on the same host can reach it:
ports: ['127.0.0.1:4533:4533']If the proxy runs in another container on the same Docker network, drop
ports:entirely and point the proxy atminstrel:4533. -
Terminate HTTPS at a reverse proxy. Any proxy works. With Caddy, which gets and renews certificates by itself:
music.example.com { reverse_proxy 127.0.0.1:4533 }Two settings matter for every proxy:
- Don't buffer responses. Live updates use Server-Sent Events and audio
is streamed; a buffering proxy holds both back. Caddy streams by default.
For nginx, set
proxy_buffering off;. - Allow long-lived responses. An event stream stays open for as long as
the app is. Raise the proxy's read timeout well past a minute (nginx:
proxy_read_timeout 1h;).
- Don't buffer responses. Live updates use Server-Sent Events and audio
is streamed; a buffering proxy holds both back. Caddy streams by default.
For nginx, set
-
Tell Minstrel where it lives, in Admin › Email & network:
- Client IP detection: the number of proxies in front of Minstrel. One proxy (Caddy, Traefik, nginx) is 1; Cloudflare in front of Traefik is 2. Minstrel uses this to find the real client address, for login rate limits and the sessions list, and to tell whether a request arrived over HTTPS.
- Public address: the URL people use, e.g.
https://music.example.com. Password-reset emails link here. Until it is set, no reset email is sent, so a forgedHostheader can never put a reset token on a link to someone else's server.
Why the proxy count matters
Minstrel only believes X-Forwarded-For and X-Forwarded-Proto from the
number of proxies you configure, counted from the right. Set it too high, or
leave it at the default of 1 with no proxy in front, and a client can write
those headers itself: it could claim any address to slip past the per-address
login limit, or claim HTTPS. With no proxy, set it to 0.
When the proxy reports HTTPS, Minstrel marks the session cookie Secure and
sends Strict-Transport-Security. Over plain HTTP it does neither, and it
never redirects to HTTPS, so LAN use keeps working unchanged.
First account
A fresh server with no accounts prints a setup token in its log:
docker compose logs minstrel | grep setup_token
Creating the first account (which becomes the admin) requires that token, so whoever reaches a newly exposed server first can't claim it. The token changes on every restart until an account exists.
Backups
Minstrel can back itself up once a night: accounts, likes, playlists, listening history and settings, in one file. It is off until an admin switches it on under Admin › Backups. Anything Minstrel can fetch or work out again (artwork, fingerprints, MusicBrainz data) is left out, and so are the keys and passwords Minstrel keeps for other services, which are entered again on a restored server. Sign-in passwords are kept.
A backup goes to one of:
- an S3 bucket, path-style (MinIO, Garage, or any S3-compatible store).
The key only needs to add and list objects. Files land under
database/. - a folder on the server, under
database/inside it. Mount a volume there; Minstrel refuses to write into a folder that isn't there.
Minstrel only adds files, named by date, and never deletes one. Keep as many as you like with the destination's own retention. Test destination lists what is there without writing anything.
Include the music also sends the library's files to music/ in the same
destination, laid out as they are under the library folders. After each
night's database file has landed, Minstrel sends the files it hasn't sent
yet, one at a time, for up to six hours; a large library takes several
nights the first time, and the panel shows how much is in. After that, a
night sends only new files and files that changed. A changed file goes to
its old name, and Minstrel still never deletes anything there, so a file
taken out of the library stays in the backup. On a bucket that keeps
versions or locks objects, set its retention to keep what you want. A file
the bucket refuses (an overwrite a locked object won't take) is listed on
the panel and goes again once it changes or the settings are saved; three
refusals in a row stop that night's music, since that is usually a key that
may not write under music/. A bucket's upload limit applies
to the music as well.
Restoring
A backup restores into a new Minstrel: one nobody has signed up to yet. If it has already scanned the music, that's fine; the backup's library takes the place of what the scan found.
- Put the music back first, at the path the library had. The restored
settings name the old library folders, and each track is found again by
its path. If the backup includes the music, copy what is inside
music/into the library folder (with several library folders, into the folder that holds them all). - Load the backup, either way:
- In the web app, choose Create account, then Restore a backup.
Pick a
minstrel-….tarfile from the backup'sdatabase/folder and enter the setup token from the log (see First account). Minstrel restarts by itself once the backup is in, so it runs on the restored settings. - Or, with the server stopped, run
docker compose run --rm minstrel restore /backups/database/minstrel-20261102T030000Z.tar, with the file on a volume the container can read. It brings the database schema up to date first, so a backup from an older Minstrel loads into a newer one; a backup from a newer Minstrel is refused.
- In the web app, choose Create account, then Restore a backup.
Pick a
- Sign in with the password you had. Everyone else's accounts, likes, playlists and history are back too.
The library scan then finds each file, and the artwork, tags, fingerprints and loudness are fetched or worked out again over the following hours. Keys for other services (ListenBrainz, AcoustID, artwork and tag providers, email) and the backup's own destination are entered again under Admin. An app that synced with the old server starts its sync over.
Android app
The app connects over whatever URL you give it, HTTP or HTTPS. Once the server has a public HTTPS address, give the app that address so the session cookie never crosses the internet unencrypted. See security notes for why plain HTTP is still allowed.