Lyra/docs/DEPLOYMENT.md

# Lyra — deployment & advanced guide

Topics beyond the [README](../README.md) quick-start: the full feature tour, publishing
pre-built images to a registry, and running the whole stack behind a VPN. For a basic
self-hosted setup you only need the README — start there.

- [Features in depth](#features-in-depth)
- [Publishing pre-built images](#publishing-pre-built-images)
- [Running behind a VPN (Gluetun)](#running-behind-a-vpn-gluetun)

---

## Features in depth

Lyra was built in three slices, all complete:

1. **Acquisition engine.** Resolve a request against MusicBrainz, match/rank across
   Qobuz/Soulseek/YouTube, download the best source into an isolated staging dir, verify
   completeness, tag (mutagen), and atomically promote the clean album into
   `Artist/Album (Year)/## Title.ext`.
2. **Library manager.** Watched artists (live MB search + follow), per-release monitor
   toggles + auto-monitor-future, a wanted list with retry + quality-upgrade window, and a
   worker "monitor" that discovers new releases and auto-grabs through the acquisition
   pipeline. Plus a **library scan** that ingests existing on-disk albums as
   have + monitored + followed, and a per-artist studio-only / show-all release-type filter.
3. **Discovery.** Recommendation-driven finding of new music via **ListenBrainz**
   similar-artists and **Last.fm** `artist.getSimilar` (both MBID-native), behind a
   pluggable `SimilaritySource` interface — Last.fm registers as a second source
   automatically once its API key is set, and cross-source scores are summed per candidate.
   A background sweep (and a "Discover now" button) aggregates artists similar to the ones
   you follow into a manual review feed of suggested **artists** and **albums** at
   `/discover`; **Follow** and **Want** reuse the slice-2 follow / wanted flows, **Dismiss**
   is permanent. Plus a web-side seed-search box. Every suggestion and seed-search result
   opens a read-only **artist preview** (`/discover/artist/[mbid]`) — discography, per-album
   tracklists, and "in library" / "monitored" badges — where you can Follow or Want before
   committing. No Spotify (its recommendation APIs are dead for new apps).

Alongside the three slices:

- **Last.fm browse** (`/lastfm`) — your Last.fm top artists and albums (by period), with a
  "hide items already in my library" toggle and inline **Follow** / **Want** buttons on each
  row; each artist also opens a modal of your most-played songs and albums.
- **Library** (`/library`) — a cover-art grid of everything on disk, filterable, each album
  opening a tracklist modal.
- **The Floor** (home) — a live queue of in-flight acquisitions with three-phase progress
  (**Searching → Downloading → Finishing**), a live download percentage, a per-job "pressing
  ticket" (source · format · tracks · elapsed), and a **Retry** button on anything that needs
  attention.

The whole UI runs a hand-rolled "Pressing Plant" design system (warm-paper theme, self-hosted
Fraunces serif for prose vs. system mono for machine data, light/dark aware).

Deferred hardening and the full roadmap live in the implementation-plan "Notes" sections under
[`docs/superpowers/plans/`](superpowers/plans/); the full design specs are under
[`docs/superpowers/specs/`](superpowers/specs/).

---

## Publishing pre-built images

> **Maintainer release process** — this is how the project maintainer publishes images to a
> private registry. If you're self-hosting your own copy, ignore this and just build from
> source with `docker compose up -d --build` (see the README). You'd only need this if you
> run your own registry and want servers to **pull** rather than build.

The `web` and `worker` images can be published to a container registry and consumed by a
compose file that pulls instead of builds. The maintainer publishes to a Gitea container
registry consumed by a compose file in the
[`vm-download`](https://git.jger.nl/Jonathan/vm-download) ops repo (`docker/lyra/`).

Publish a new release from this repo (amd64):

```sh
docker login <your-registry>       # once — registry user + a token with package:write
./scripts/build-push.sh            # builds + pushes lyra-web / lyra-worker (:latest and :<sha>)
```

`scripts/build-push.sh` defaults the registry namespace to `git.jger.nl/jonathan`; override it
with `LYRA_REGISTRY=<your-registry>/<namespace>`.

Then on the server:

```sh
cd /opt/git/vm-download && git pull
cd docker/lyra && docker compose pull && docker compose up -d
```

`db` (Postgres) and `db-backup` use the stock `postgres:17` image, so only the two custom
images are built here.

---

## Running behind a VPN (Gluetun)

Lyra runs fine with its traffic routed through a [Gluetun](https://github.com/qdm12/gluetun)
VPN container — useful for hiding the download traffic (Soulseek / Qobuz / YouTube). Nothing
in Lyra is VPN-incompatible; the only thing that changes is container networking, because a
service using `network_mode: "service:gluetun"` gives up its own network stack and shares
Gluetun's. Two consequences:

- Containers that share Gluetun's namespace reach each other over **`localhost`**, not by
  Docker service name — so `DATABASE_URL` changes from `@db:5432` to **`@localhost:5432`**.
- **Published ports move to the `gluetun` container** (the individual services can no longer
  publish their own).

The simplest, most consistent setup is to put the **whole stack** behind Gluetun. Sketch
(merge into your existing Gluetun compose; adjust the VPN provider block to yours):

```yaml
services:
  gluetun:
    image: qmcgaw/gluetun
    cap_add: [NET_ADMIN]
    environment:
      # ... your VPN provider / credentials ...
      FIREWALL_INPUT_PORTS: "3000"                 # let your browser reach the web UI
      FIREWALL_OUTBOUND_SUBNETS: "192.168.0.0/16"  # your LAN — so the worker can reach slskd
    ports:
      - "8770:3000"   # Lyra web  (published on gluetun, not on `web`)
      # - "5432:5432" # only if you want DB access from the LAN

  web:
    build: ./web
    network_mode: "service:gluetun"     # no `ports:` / `networks:` here
    environment:
      DATABASE_URL: postgresql://lyra:lyra@localhost:5432/lyra   # `db` -> `localhost`
      LYRA_SECRET_KEY: ${LYRA_SECRET_KEY}
      LYRA_PASSWORD: ${LYRA_PASSWORD:-}
      HOSTNAME: 0.0.0.0
      LYRA_LIBRARY_ROOT: /music
    volumes:
      - ${MUSIC_DIR:-./music}:/music
    depends_on:
      gluetun: { condition: service_healthy }
      db: { condition: service_healthy }

  worker:
    build: ./worker
    network_mode: "service:gluetun"
    environment:
      DATABASE_URL: postgresql://lyra:lyra@localhost:5432/lyra
      LYRA_SECRET_KEY: ${LYRA_SECRET_KEY}
      STAGING_ROOT: /staging
      SLSKD_DOWNLOADS_ROOT: /slskd-downloads
    volumes:
      - ${MUSIC_DIR:-./music}:/music
      - ${STAGING_DIR:-${MUSIC_DIR:-./music}/.staging}:/staging
      - ${SLSKD_DOWNLOADS_DIR:-./slskd-downloads}:/slskd-downloads
    depends_on:
      gluetun: { condition: service_healthy }
      db: { condition: service_healthy }

  db:
    image: postgres:17
    network_mode: "service:gluetun"     # shares the namespace so `localhost:5432` resolves
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - postgres-data:/var/lib/postgresql/data
```

(Give `db-backup` the same `network_mode` and `PGHOST: localhost`.) The `HOSTNAME=0.0.0.0`
and the built-in healthchecks keep working, since everything is in one namespace.

Caveats worth knowing:

- **Qobuz is geo-sensitive** — its catalog/availability varies by country, so pick a VPN
  exit in a region where your Qobuz account works, or some downloads will fail to match.
- The worker's `net.ipv6.conf.all.disable_ipv6` sysctl **can't apply behind Gluetun** (a
  shared netns can't set sysctls) — harmless, because Gluetun blocks IPv6 anyway, which is
  exactly what that sysctl worked around (Qobuz's CDN resolving to an unroutable IPv6).
- MusicBrainz rate-limits per IP; a shared VPN exit is marginally more likely to hit the
  1 req/s ceiling, but the built-in response cache makes that a non-issue in normal use.
- Bind mounts (`/music`, `/staging`, `/slskd-downloads`), the Postgres volume, and backups
  are filesystem, not network — **completely unaffected** by the VPN.