Files
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

81 lines
6.0 KiB
Markdown

# ansible-role-funkwhale
Deploys [Funkwhale](https://funkwhale.audio) 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](https://gitea.eom.dev/DevOps/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:
```sh
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
```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