ericandClaude Opus 5.5 8c0c4e16dd Own LDAP account and mail: funkwhale@eom.dev
tasks/ldap.yml keeps cn=Funkwhale (password from Vault, in Funkwhale Users,
Postfix Users and Dovecot Users). Mail goes out as funkwhale@eom.dev instead
of listmonk's news account, and the account is a Dex superuser.

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

ansible-role-funkwhale

Deploys Funkwhale 2.0.13, eom.dev's federated music and podcast server, to Kubernetes as plain manifests.

It fits in with the rest of eom.dev:

  • Login is Dex only, through the funkwhale-oidc plugin. Every login form shows the "eom.dev account" button, and /login and /signup go straight to Dex.
    • Any account Dex lets through gets a Funkwhale account on first login, with a federation actor and libraries.
    • Users listed in funkwhale_oidc_admin_users become superusers.
    • Local login is off (funkwhale_oidc_local_login: false): the server refuses password login, sign-up and password reset. If Dex is down, use kubectl exec and funkwhale-manage in the API pod. Set it to true to get the break-glass breakglass login back at /login?local=1.
  • Anonymous access is on: anyone can browse and listen to public content without an account.
  • Look: Catppuccin Latte in light mode and Mocha in dark mode, matching dex.eom.dev, listmonk and www. Users can still pick light, dark or auto.
    • The front links files/catppuccin.css from index.html (ConfigMap funkwhale-theme, hook files/theme.sh, which also bumps the service worker's precache revision for index.html so returning visitors get the new page), so the theme is there on first paint.
    • It covers the neutral surfaces, every alert/tag palette, mauve links and buttons, the font, and the welcome page: a Catppuccin gradient and the eom.dev logo instead of the sky-blue banner and whales.
    • The palette block is generated by tools/gen-palettes.py.
    • Firefox ESR 140 has no CSS @scope, and Funkwhale 2.x defines its text and surface colour scales only inside @scope blocks. Without a fix, text there renders black. files/compat.js adds no-css-scope to <html> in such browsers, and catppuccin.css then supplies the same scales as plain selectors. Browsers that support @scope ignore it.
  • Mail goes out through postfix.eom.dev:587 as Funkwhale's own LDAP account funkwhale (funkwhale@eom.dev).
  • LDAP account: tasks/ldap.yml keeps cn=Funkwhale,ou=Funkwhale,ou=Services. It creates the account if it's missing, sets its password from Vault and adds it to Funkwhale 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 a Funkwhale superuser (funkwhale_oidc_admin_users).
  • Cluster conventions: ca-issuer TLS, nfs-client volumes, and anti-affinity that keeps the pods off the ingress-nginx node.

What it creates

Object Purpose
Secret/funkwhale Django key, DB password, SMTP URL, break-glass admin password, Dex client secret
ConfigMap/funkwhale Everything else, as environment variables
StatefulSet/funkwhale-db PostgreSQL 17 (alpine, uid 70)
Deployment/funkwhale-redis Cache and Celery broker; no persistence
Deployment/funkwhale-api Gunicorn. Init containers install the plugin, then run migrate and collectstatic
Deployment/funkwhale-celeryworker, -celerybeat Background jobs (imports, federation, transcoding) and their scheduler
Deployment/funkwhale-front Funkwhale's nginx and web app, with the plugin's login button, its /accounts/ route and the theme stylesheet
ConfigMap/funkwhale-theme catppuccin.css, compat.js and the index.html hook
PVC/funkwhale-{media,music,static} Uploads, in-place music library, Django static files (RWX)
Ingress/funkwhale https://funkwhale.eom.dev

Every pod that loads Funkwhale's settings runs a plugins init container. It pip-installs funkwhale_oidc_plugin_url (a tagged archive from Gitea) and PyJWT into an emptyDir, so the stock images are used unchanged.

Instance settings live in Funkwhale's database. The role writes the ones in funkwhale_preferences / funkwhale_preferences_extra on every run, using templates/configure.py.j2 run inside the API pod. That covers the name, descriptions, anonymous access and sign-up. It also clears the in-app theme settings, because the stylesheet replaces them. While local login is on, the same script also creates the break-glass admin or resets its password. Anything else stays under the admin UI's control.

Secrets

Variable Notes
funkwhale_oidc_client_secret Required. Must match the funkwhale client in Dex. Vault: funkwhale_dex_client_secret
funkwhale_smtp_password Required. Password of the funkwhale LDAP account; the role sets it in LDAP if it differs. Vault: funkwhale_admin_password (on eom.dev the same Vault key also sets the break-glass funkwhale_admin_password)
funkwhale_django_secret_key, funkwhale_db_password, funkwhale_admin_password Optional; the admin password only matters while local login is on. If empty, they are generated on the first run, stored in Secret/funkwhale and reused afterwards

To read the break-glass password:

kubectl -n funkwhale get secret funkwhale -o jsonpath='{.data.FUNKWHALE_CLI_USER_PASSWORD}' | base64 -d

One-time setup outside this role

Add the funkwhale client to Dex (ericomeehan.dex/playbooks/deploy-eom.yml) with this redirect URI, then run that play:

https://funkwhale.eom.dev/accounts/oidc/dex/login/callback/

Upgrading Funkwhale

  1. Bump funkwhale_version.
  2. Run the plugin's end-to-end test (funkwhale-oidc/tests/compose.yaml) against the new version.
  3. Check that the theme still applies. It overrides the --color-default-* and --fw-* variables from front/src/ui/fw.css, and matches the welcome page's CSS-module class names (_banner_, _logo_, _loginCard_) from components/Home.vue.

Never change funkwhale_host after the first deploy. Every federated object 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

S
Description
Ansible role to deploy Funkwhale to Kubernetes
Readme MIT-0
114 KiB
Languages
CSS 52.6%
Jinja 40.5%
Python 4.1%
Shell 2.3%
JavaScript 0.5%