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>
81 lines
6.0 KiB
Markdown
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
|