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

ansible-role-harmony

Deploys 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

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).

S
Description
Ansible role to deploy Harmony to Kubernetes
Readme MIT-0
97 KiB
Languages
Jinja 65.3%
CSS 17.2%
PLpgSQL 10.7%
Shell 4.6%
Python 2.2%