minstrel/docs/hosting.md

# 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, requests 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: an empty database, with no accounts
and no library yet.

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*).
   - 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, download clients) 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.