Esa Kataja
992caa4eb1
docs/deployment.md is the server-side procedures: the compose file a server runs, building and publishing a release, first deployment, reverse proxy, upgrades and rollback, backups and restore, and a troubleshooting table. The compose file lives in the manual rather than in the repository, because the one at the root builds from source and is what development wants. The server's pulls a published image, pins a release tag, and publishes the admin port on the host's loopback instead of every interface — the panel is Basic Auth and nothing else, so where that port is bound is the whole of its security. .dockerignore keeps the image build off storage/ (the live database and the audio), .env (the admin password) and the leftover pgdata, which the build cannot read anyway and which fails it outright.
173 lines
6.7 KiB
Markdown
173 lines
6.7 KiB
Markdown
# Levyraati
|
||
|
||
A private music review club. Members submit songs — by file upload or YouTube link — and review each
|
||
other's picks on a 1–100 scale. Other people's reviews of a song stay hidden until you've written
|
||
your own.
|
||
|
||
Invite-only, no public registration. Built for about ten friends.
|
||
|
||
> **Status:** not built yet. This README describes the app defined in [docs/spec.md](docs/spec.md);
|
||
> commands here are the intended interface, not a record of anything that runs today.
|
||
|
||
## Docs
|
||
|
||
| File | What's in it |
|
||
|---|---|
|
||
| [CONTEXT.md](CONTEXT.md) | The glossary — every domain term, in English and Finnish |
|
||
| [docs/spec.md](docs/spec.md) | What the app does: rules, pipeline, routes, API contract, schema |
|
||
| [docs/decisions.md](docs/decisions.md) | Why it is that way. Append-only |
|
||
| [docs/theme.md](docs/theme.md) | The visual language: tokens, type, and what differs from the theme handoff |
|
||
| [docs/later.md](docs/later.md) | Deliberately not in v1, with the reasoning kept |
|
||
| [docs/deployment.md](docs/deployment.md) | Running it on a server: the compose file, releases, upgrades, backups |
|
||
|
||
## Branches and releases
|
||
|
||
- **`main`** — released code only. Every commit on it is something that ran in production, or is
|
||
meant to. Tagged at each release.
|
||
- **`dev`** — current development, and whatever nightly builds get made. Work happens here and
|
||
reaches `main` by merge at release time.
|
||
|
||
Versions are **CalVer: `YYYY.MM.DD-N`**, where `N` is the build number for that day, starting at 1.
|
||
The version is injected at build time, so no file in the repo carries it:
|
||
|
||
```sh
|
||
git switch main && git merge --no-ff dev
|
||
git tag 2026.07.31-1
|
||
VERSION=$(git describe --tags --exact-match) docker compose build app
|
||
docker compose up -d app
|
||
```
|
||
|
||
A plain `go build` reports `dev`, which is the honest answer for a local binary. The running
|
||
version appears in the footer, in the startup log line, and in `GET /healthz` — so "what is
|
||
actually deployed" is answerable without an SSH session.
|
||
|
||
The app never sends email — there is no verification, no password reset link, and no notifications.
|
||
Members have an address because it is their login and because mail is a planned feature.
|
||
|
||
## Stack
|
||
|
||
Go, SQLite, `html/template`, HTMX + Alpine. Audio is converted with ffmpeg and downloaded with
|
||
yt-dlp. One binary, one origin, one container — there is no separate frontend and no database server
|
||
to deploy.
|
||
|
||
Go dependencies: `modernc.org/sqlite` and `golang.org/x/crypto`. The SQLite driver is pure Go, so the
|
||
build stays `CGO_ENABLED=0`. No Node, no npm, no bundler.
|
||
|
||
## Running it
|
||
|
||
```sh
|
||
cp .env.example .env # then edit — ADMIN_PASSWORD has no default and the app won't start without it
|
||
docker compose up -d
|
||
```
|
||
|
||
Migrations apply themselves at startup, before the server accepts connections. The first launch
|
||
creates no users: log into the admin panel and mint an invite.
|
||
|
||
### Configuration
|
||
|
||
| Variable | Default | Notes |
|
||
|---|---|---|
|
||
| `DB_PATH` | `$STORAGE_DIR/levyraati.db` | The SQLite file. Created on first start |
|
||
| `ADMIN_USER` | `admin` | Admin panel username |
|
||
| `ADMIN_PASSWORD` | — | **Required.** No default; the app refuses to start without it |
|
||
| `ADDR` | `:8080` | Member-facing listener |
|
||
| `ADMIN_ADDR` | `127.0.0.1:8081` | Admin listener. Keep it on loopback. Under Compose it binds `:8081` inside the container and is published only to the host's loopback |
|
||
| `STORAGE_DIR` | `./storage` | Audio, avatars, in-flight conversions |
|
||
| `SECURE_COOKIES` | `true` | Set `false` for local development over plain HTTP |
|
||
| `PUBLIC_URL` | — | Public address of the member site, e.g. `https://levyraati.example.com`. Used to build invite links in the admin panel; unset gives relative links |
|
||
|
||
### Local development
|
||
|
||
```sh
|
||
export ADMIN_PASSWORD=dev SECURE_COOKIES=false
|
||
go run .
|
||
```
|
||
|
||
Requires Go 1.25+, plus `ffmpeg`, `ffprobe`, and `yt-dlp` on `PATH`. There is nothing to start first:
|
||
the database is a file under `./storage`, created on the first run.
|
||
|
||
Tests get a fresh database file in a temp directory each, so they need no setup and touch nothing:
|
||
|
||
```sh
|
||
go test ./...
|
||
```
|
||
|
||
Templates, stylesheet, and migrations are embedded with `embed.FS`, so a rebuild is needed to see
|
||
template changes. `go build && ./levyraati` is the loop.
|
||
|
||
## Admin panel
|
||
|
||
The admin is **not a user account**. It exists only as `ADMIN_USER` / `ADMIN_PASSWORD`, authenticates
|
||
with HTTP Basic Auth, and is bound to loopback so it is not reachable from the internet. Reach it
|
||
through an SSH tunnel:
|
||
|
||
```sh
|
||
ssh -L 8081:127.0.0.1:8081 you@server
|
||
# then open http://localhost:8081
|
||
```
|
||
|
||
From there: mint invites, reset member passwords, ban members, delete songs, read issue reports.
|
||
|
||
**Lost the admin password?** Edit `.env` and `docker compose restart app`. There is no recovery
|
||
endpoint and no recovery key — the credentials are the environment.
|
||
|
||
## Operations
|
||
|
||
### yt-dlp goes stale
|
||
|
||
yt-dlp needs regular updates to keep working against YouTube. It comes from Alpine's community
|
||
repository, whose active branch tracks upstream closely, so rebuilding is how you update it:
|
||
|
||
```sh
|
||
docker compose build --no-cache app && docker compose up -d app
|
||
```
|
||
|
||
**Rebuild monthly.** When submissions start failing with download errors, this is the first thing to
|
||
try. Failures are shown to the submitter with the yt-dlp error attached, so they're visible without
|
||
reading logs.
|
||
|
||
### Logs
|
||
|
||
```sh
|
||
docker compose logs -f app
|
||
```
|
||
|
||
JSON to stdout, nothing else. There is no log table and no log viewer in the app.
|
||
|
||
### Backups
|
||
|
||
`./storage` holds everything: audio files, avatars, and `levyraati.db`. It is a bind mount, so a copy
|
||
of that one directory is the whole backup. `storage/tmp/` is in-flight conversions and is safe to
|
||
skip; it's cleared on startup anyway.
|
||
|
||
Copying the file while the app is running is not a backup — WAL means the latest writes live in a
|
||
sidecar file. Ask SQLite for a consistent snapshot instead:
|
||
|
||
```sh
|
||
docker compose exec app sqlite3 /storage/levyraati.db ".backup '/storage/tmp/backup.db'"
|
||
gzip -c storage/tmp/backup.db > backup-$(date +%F).db.gz && rm storage/tmp/backup.db
|
||
```
|
||
|
||
### Database shell
|
||
|
||
```sh
|
||
docker compose exec app sqlite3 /storage/levyraati.db
|
||
```
|
||
|
||
## Layout
|
||
|
||
Go source is flat at the repository root, one package. Beyond that: `templates/` and `static/` are
|
||
embedded assets, `migrations/` holds numbered `.sql` files applied in order at startup, and
|
||
`testdata/` holds the golden JSON files that guard the API contract, plus `ytdlp-noose.json` — a real
|
||
`yt-dlp -J` dump of an ordinary upload, used to test metadata prefill against a video that has no
|
||
`track`, `artist` or `album` at all.
|
||
|
||
## Notes
|
||
|
||
Downloading audio from YouTube is against YouTube's terms of service. This is a private app among a
|
||
handful of friends; the decision is deliberate rather than accidental.
|
||
|
||
## Licence
|
||
|
||
MIT — see [LICENSE](LICENSE).
|