Files
claudeandClaude Opus 5.5 99687ea231 Own LDAP account and mail, Harmony Users gate, Dex-only sign-in UI
- tasks/ldap.yml keeps cn=Harmony (harmony@eom.dev): password from Vault,
  in Harmony Users, Postfix Users and Dovecot Users. GoTrue sends as it,
  and it is an instance admin alongside eric@eom.dev.
- theme.js hides the e-mail/password form; Register and /register (also in
  Caddy) go to https://www.eom.dev/members/.
- The Dex button uses the square eom.dev icon.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 17:44:29 -05:00

95 lines
8.4 KiB
Markdown

# ansible-role-harmony
Deploys [Harmony](https://github.com/y4my4my4m/harmony) 1.9.6 to Kubernetes as plain manifests. Harmony is a federated, Discord-like chat with voice and video. On eom.dev it runs as **Harmony on eom.dev** at `https://harmony.eom.dev`.
Upstream supports Docker Compose only, through `self-host/` with Supabase pulled in by `include:`. This role is a Kubernetes port of that stack at the same versions, and it fits in with the rest of eom.dev:
- **Sign-in** is Dex only, and only for members of the **Harmony Users** LDAP group. Dex's `harmony` connector admits only that group. GoTrue (Supabase's auth service) runs the OIDC exchange with `dex.eom.dev` as a custom provider (`custom:dex`).
- E-mail/password sign-in and sign-up are off at GoTrue (`harmony_email_login: false`). `templates/theme.js.j2` hides the sign-in page's e-mail form.
- "Register" and any visit to `/register` go to `harmony_signup_url` (https://www.eom.dev/members/). `theme.js` handles in-app navigation, and Caddy handles direct loads.
- Each person admitted gets a Harmony account on their first sign-in. A Dex sign-in never joins an existing account by address (`PROVIDER_LINKING_DOMAINS custom:dex=custom:dex`).
- Addresses in `harmony_admin_emails` (harmony@eom.dev, eric@eom.dev) become instance admins on the first run after that person signs in.
- **Look**: Catppuccin Mocha in dark mode and Latte in light mode, with a mauve accent, matching `dex.eom.dev`, Funkwhale and www.
- The theme is a stylesheet linked from `index.html` by an entrypoint hook. See `files/theme/README-THEME.md`.
- It applies to Harmony's stock Dark and Light themes only. Midnight, custom themes, community presets and skins still look the way Harmony ships them.
- **Voice and video**: LiveKit, with signalling at `wss://voice.harmony.eom.dev` through the ingress. Media goes over 7881/tcp and 7882/udp on a MetalLB address (see *Voice* below).
- **Mail**: GoTrue's invitation mail goes out through `postfix.eom.dev:587` as Harmony's own LDAP account `harmony` (harmony@eom.dev).
- **LDAP account**: `tasks/ldap.yml` keeps `cn=Harmony,ou=Harmony,ou=Services`. It creates the account if it's missing, sets its password from Vault and adds it to Harmony Users, Postfix Users and Dovecot Users. It runs in the OpenLDAP pod as `cn=admin`, like ericomeehan.www's groups. Signing in through Dex, the account is an instance admin.
- **Cluster conventions**: `ca-issuer` TLS, `nfs-client` volumes, and anti-affinity that keeps pods off the ingress-nginx node.
## Licence obligations (Harmony is AGPL-3.0 with §7 terms)
- The "Powered by Harmony" link on the sign-in page must stay visible and unaltered. The theme only recolours the page around it.
- The name follows Harmony's trademark policy (`TRADEMARK.md`). The app code runs unmodified; only a stylesheet is added, and the Harmony logo is not used as a brand. "Harmony on eom.dev" names a hosted instance, which the policy allows. A *modified version* distributed under the name "Harmony" is not allowed, so if this role ever patches Harmony's code, rename the instance or ask the maintainers first (they say they default to yes for community use).
- AGPL §13: the changes this role makes to Harmony's files are public in this repository: the theme, `files/Caddyfile`, and the media-cache and Kong configs.
- `files/Caddyfile` is Harmony's own file and stays under Harmony's licence. `files/supabase-db/*.sql` and `templates/kong.yml.j2` derive from Supabase (Apache-2.0). Everything else in the role is MIT-0.
## What it creates (namespace `harmony`)
| Object | Purpose |
| --- | --- |
| `Secret/harmony` | JWT secret, anon and service-role keys, Postgres, Redis and listener passwords, VAPID pair, LiveKit keys, SMTP and Dex secrets |
| `StatefulSet/harmony-db`, `Service/supabase-db` | `supabase/postgres` with Supabase's init SQL (`ConfigMap/harmony-db-init`) and a PVC for pgsodium's key |
| `Deployment/harmony-{auth,rest,realtime,storage,imgproxy,kong}` | GoTrue, PostgREST, Realtime, storage-api (files on the RWX PVC `harmony-files`), imgproxy, Kong. Each has a Service named as in the compose stack (`auth`, `rest`, `realtime-dev`, `storage`, `imgproxy`, `supabase-kong`) |
| `Deployment/harmony-web` | The SPA (nginx). It writes `config.json` from its environment and links the theme (`ConfigMap/harmony-theme`) |
| `Deployment/harmony-federation-{server,worker}` | Harmony's Node backend: ActivityPub, link previews, push, LiveKit tokens and webhooks, and BullMQ queues |
| `Deployment/harmony-redis` | Queues, cache and presence (AOF on a PVC) |
| `Deployment/harmony-media-cache` | nginx cache for public storage reads |
| `Deployment/harmony-caddy` | Harmony's own router (`files/Caddyfile`, plain HTTP). It routes by path, `Accept`, `User-Agent` and cookie, which ingress-nginx can't do |
| `Ingress/harmony` | `harmony.eom.dev`, `api.harmony.eom.dev` and `voice.harmony.eom.dev`, all to Caddy |
| `Deployment/harmony-livekit`, `Service/livekit`, `Service/livekit-media` | SFU. Config in `Secret/harmony-livekit`; LoadBalancer `192.168.1.177` for media |
| `Job/harmony-bootstrap` | Harmony's `self-host/bootstrap.sh`, unchanged, from the release tag |
Studio, pg-meta, Edge Functions, Logflare/vector, Supavisor, the bot gateway and the Discord bridge are not deployed. In the compose stack they are optional profiles or disabled.
### Database migrations
Each run replaces `Job/harmony-bootstrap`. Its steps:
1. Clones Harmony at `v{{ harmony_version }}`.
2. Runs `self-host/bootstrap.sh` with `files/docker-shim.sh` as `docker`, so its `docker exec … psql` calls become psql over the network.
3. The script applies each pending migration once, recorded in `supabase_migrations.schema_migrations`.
4. It provisions the `harmony_listener` role and writes the upload ceiling and storage origin.
5. On a new database only, it names the instance.
`tasks/configure.yml` then does what `harmony auth add-provider`, `harmony registration open` and admin promotion do in the compose stack. It goes through Kong's ClusterIP from the control-plane node (`harmony_admin_api_url` overrides that).
## Secrets
| Variable | Notes |
| --- | --- |
| `harmony_oidc_client_secret` | **Required.** Must match the `harmony` client in Dex. Vault: `harmony_dex_client_secret` |
| `harmony_smtp_password` | **Required.** Password of the `harmony` LDAP account; the role sets it in LDAP if it differs. Vault: `harmony_admin_password` |
| `harmony_jwt_secret`, `harmony_postgres_password` | Optional. If empty, they are generated on the first run, kept in `Secret/harmony` and reused. Never change either on a running instance |
Everything else (Redis, listener, LiveKit, VAPID, Realtime's key base, the anon and service-role keys) is generated once and kept in `Secret/harmony`. The anon and service-role keys are derived from the JWT secret by `files/genkeys.py`, on the control-plane node, which needs Python `cryptography`. Back up `Secret/harmony` together with the database: it holds the only copy of these keys.
## One-time setup outside this role
1. In Dex (`ericomeehan.dex/playbooks/deploy-eom.yml`), add a `harmony` LDAP connector that admits Harmony Users, and the `harmony` client limited to it with redirect URI `https://api.harmony.eom.dev/auth/v1/callback`. Then run that play.
2. **Voice:** on the router, forward **7881/tcp** and **7882/udp** to **192.168.1.177**. LiveKit learns the public address through STUN (`use_external_ip`). Without the UDP forward, calls connect but carry no audio. Without either forward, voice fails.
## Upgrading Harmony
1. Read upstream's CHANGELOG and diff `self-host/` between the two tags:
- `docker-compose.yml`, `supabase-overrides.yml` and the image minimums in `configure.sh` (`GOTRUE_MIN`, `STORAGE_MIN`, `REALTIME_MIN`) map to the image and env settings here.
- `Caddyfile` maps to `files/Caddyfile` (keep the header's changes).
- `media-cache.conf` maps to `templates/media-cache.conf.j2`.
- The pinned `SUPABASE_REF` maps to `files/supabase-db/` and `templates/kong.yml.j2`.
2. Bump `harmony_version`. The bootstrap Job applies the new migrations.
3. Re-check the theme against `files/theme/README-THEME.md`.
Never change `harmony_domain` after the first deploy. Every federated object and stored file URL carries it.
## Testing
```sh
ansible-playbook -i tests/inventory tests/render.yml # renders into .render/
```
To validate against the cluster without changing anything, pipe the rendered manifests into `kubectl apply --dry-run=server -f -`.
## License
MIT-0 (see *Licence obligations* for the vendored files).