Gateway: README with env vars, deploy, security #11

New issue

Closed

opened 2026-08-09 20:31:47 +00:00 by hermes · 1 comment

hermes commented

2026-08-09 20:31:47 +00:00

Owner

Context

Gateway service (see #18). The README is what the owner and other agents
use to deploy.

Task

README.md covering:

env var table (names + purpose, all 7 from #2)
deploy: docker run example with -e vars, a volume for the SQLite DB,
a reverse proxy (Caddy/Traefik) for HTTPS — the registered MusicKit
redirect URI must be https
one-time login: visit /login, click Connect, done
API table (/api/v1/status, /playlists, /playlists/{id}/tracks,
DELETE /api/v1/login, /healthz) with bearer auth
security: SERVICE_TOKEN and the .p8 key are secrets; token stored in
owner-only SQLite; callback query strings are never logged
link to the beets plugin (coop/beets-appleplaylists) as the intended
client

Acceptance criteria

README committed; an agent can deploy the image from it without asking
questions.

## Context Gateway service (see #18). The README is what the owner and other agents use to deploy. ## Task `README.md` covering: - env var table (names + purpose, all 7 from #2) - deploy: `docker run` example with `-e` vars, a volume for the SQLite DB, a reverse proxy (Caddy/Traefik) for HTTPS — the registered MusicKit redirect URI must be https - one-time login: visit `/login`, click Connect, done - API table (`/api/v1/status`, `/playlists`, `/playlists/{id}/tracks`, `DELETE /api/v1/login`, `/healthz`) with bearer auth - security: `SERVICE_TOKEN` and the `.p8` key are secrets; token stored in owner-only SQLite; callback query strings are never logged - link to the beets plugin (`coop/beets-appleplaylists`) as the intended client ## Acceptance criteria - README committed; an agent can deploy the image from it without asking questions.

hermes added the

docs

label

2026-08-09 20:31:47 +00:00

hermes commented

2026-08-11 17:27:52 +00:00

Author

Owner

Done. README.md rewritten (commit 460219c) and verified against the implementation:

env var table with all 7 vars from #2 (6 required + optional GATEWAY_DB_PATH), names + purpose + required flag
deploy: docker run example with -e vars, a named volume for the SQLite DB (GATEWAY_DB_PATH), unprivileged container, healthcheck note; reverse-proxy section (Caddy example) making the redirect URI https
one-time login walkthrough: visit /login, click Connect Apple Music, sign in, "Linked" page
API table: /healthz, /login, /callback, /api/v1/status, /api/v1/playlists, /api/v1/playlists/{id}/tracks, DELETE /api/v1/login — with bearer-auth requirement and the Apple 401/403 -> 502 re-login hint
security: SERVICE_TOKEN + .p8 are secrets, owner-only SQLite, query strings never logged (access-log scrubber)
link to coop/beets-appleplaylists as the intended client

The README documents the pipeline-built image (git.sams.wtf/coop/apple-music-gateway:<version> / latest), matching pipeline.yaml and the Dockerfile.

Done. `README.md` rewritten (commit `460219c`) and verified against the implementation: - env var table with all 7 vars from #2 (6 required + optional `GATEWAY_DB_PATH`), names + purpose + required flag - deploy: `docker run` example with `-e` vars, a named volume for the SQLite DB (`GATEWAY_DB_PATH`), unprivileged container, healthcheck note; reverse-proxy section (Caddy example) making the redirect URI https - one-time login walkthrough: visit `/login`, click Connect Apple Music, sign in, "Linked" page - API table: `/healthz`, `/login`, `/callback`, `/api/v1/status`, `/api/v1/playlists`, `/api/v1/playlists/{id}/tracks`, `DELETE /api/v1/login` — with bearer-auth requirement and the Apple 401/403 -> 502 re-login hint - security: `SERVICE_TOKEN` + `.p8` are secrets, owner-only SQLite, query strings never logged (access-log scrubber) - link to `coop/beets-appleplaylists` as the intended client The README documents the pipeline-built image (`git.sams.wtf/coop/apple-music-gateway:<version>` / `latest`), matching `pipeline.yaml` and the Dockerfile.

hermes closed this issue

2026-08-11 17:27:52 +00:00