Kubernetes port of Harmony 1.9.6's self-host compose stack (Supabase Postgres, GoTrue, PostgREST, Realtime, storage-api, imgproxy, Kong; Harmony web, federation server/worker, Redis, media cache, Caddy router; LiveKit) at harmony.eom.dev, api.harmony.eom.dev and voice.harmony.eom.dev. - Dex is the only sign-in (GoTrue custom OIDC provider custom:dex); e-mail login off; listed addresses become instance admins. - Upstream bootstrap.sh runs unchanged in a Job through a docker shim. - Catppuccin Mocha/Latte stylesheet injected into the stock web image. - Secrets generated once and kept in Secret/harmony. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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. GoTrue (Supabase's auth service) runs the OIDC exchange with
dex.eom.devas a custom provider (custom:dex), and the sign-in page shows an "eom.dev account" button.- Every account Dex lets through gets a Harmony account on its first sign-in.
- E-mail/password sign-in and sign-up are off at GoTrue (
harmony_email_login: false). A Dex sign-in never joins an existing account by address (PROVIDER_LINKING_DOMAINS custom:dex=custom:dex). - Addresses in
harmony_admin_emailsbecome 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.htmlby an entrypoint hook. Seefiles/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.
- The theme is a stylesheet linked from
- Voice and video: LiveKit, with signalling at
wss://voice.harmony.eom.devthrough the ingress. Media goes over 7881/tcp and 7882/udp on a MetalLB address (see Voice below). - Mail: GoTrue's invitation and recovery mail goes out through
postfix.eom.dev:587as the LDAP accountnews, the same as listmonk and Funkwhale. - Cluster conventions:
ca-issuerTLS,nfs-clientvolumes, 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/Caddyfileis Harmony's own file and stays under Harmony's licence.files/supabase-db/*.sqlandtemplates/kong.yml.j2derive 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:
- Clones Harmony at
v{{ harmony_version }}. - Runs
self-host/bootstrap.shwithfiles/docker-shim.shasdocker, so itsdocker exec … psqlcalls become psql over the network. - The script applies each pending migration once, recorded in
supabase_migrations.schema_migrations. - It provisions the
harmony_listenerrole and writes the upload ceiling and storage origin. - 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 news LDAP account. Vault: listmonk_smtp_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
- Add the
harmonyclient to Dex (ericomeehan.dex/playbooks/deploy-eom.yml) with redirect URIhttps://api.harmony.eom.dev/auth/v1/callback, then run that play. - 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
- Read upstream's CHANGELOG and diff
self-host/between the two tags:docker-compose.yml,supabase-overrides.ymland the image minimums inconfigure.sh(GOTRUE_MIN,STORAGE_MIN,REALTIME_MIN) map to the image and env settings here.Caddyfilemaps tofiles/Caddyfile(keep the header's changes).media-cache.confmaps totemplates/media-cache.conf.j2.- The pinned
SUPABASE_REFmaps tofiles/supabase-db/andtemplates/kong.yml.j2.
- Bump
harmony_version. The bootstrap Job applies the new migrations. - 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).