release / go (push) Successful in 1m54s
release / web (push) Failing after 5s
release / integration (push) Failing after 3m44s
release / govulncheck (push) Successful in 20s
release / Attach APK to the Release (tag releases only) (push) Canceled after 0s
release / Build + push container image (push) Canceled after 0s
release / Verify release artifacts (tag releases only) (push) Canceled after 0s
release / Build signed APK (push) Canceled after 19s
release / android (push) Canceled after 2m37s
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>
158 lines
7.0 KiB
Markdown
158 lines
7.0 KiB
Markdown
# 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`:
|
||
|
||
```yaml
|
||
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:
|
||
|
||
1. **Don't publish 4533 to the world.** Bind it to the loopback interface so
|
||
only the proxy on the same host can reach it:
|
||
|
||
```yaml
|
||
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 at `minstrel:4533`.
|
||
|
||
2. **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;`).
|
||
|
||
3. **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 forged `Host` header 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.
|
||
|
||
1. **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).
|
||
2. **Load the backup**, either way:
|
||
- In the web app, choose **Create account**, then **Restore a backup**.
|
||
Pick a `minstrel-….tar` file from the backup's `database/` 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.
|
||
3. **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](./security.md#android-allows-plain-http) for why plain HTTP
|
||
is still allowed.
|