docs(roles): add argument_specs and README for traefik, authentik, drawio, garage, nextcloud

Each of the five roles touched in this branch now ships:

* meta/argument_specs.yml: typed schema for every variable in
  defaults/main.yml plus the optional inputs surfaced via this
  branch (traefik_extra_hosts, authentik_host_rewrite_domains,
  authentik_proxy_apps.mode / .allowed_groups, drawio_extra_domains,
  drawio_authentik_forward_auth*, garage_webui_authentik_forward_auth*).
  All five specs load cleanly through ansible-core's
  ArgumentSpecValidator.

* README.md: replaces the ansible-galaxy boilerplate (where it was
  still in place) with a focused write-up — service vars, required
  secrets, ForwardAuth/idempotency notes, dependencies, and a working
  example playbook. authentik and garage READMEs are rewritten to cover
  the new knobs while preserving their existing content.
This commit is contained in:
Simon Bärlocher 2026-05-26 14:16:47 +02:00
parent 1f9292cc9a
commit 14c81657d7
No known key found for this signature in database
GPG key ID: 63DE20495932047A
10 changed files with 1348 additions and 143 deletions

123
roles/nextcloud/README.md Normal file
View file

@ -0,0 +1,123 @@
# Nextcloud
Ansible role to deploy [Nextcloud](https://nextcloud.com/) (fpm) with
Postgres and Redis via Docker Compose, optional Collabora WOPI
integration, optional draw.io integration, optional notify_push
companion, optional S3 primary storage, plus OIDC and LDAP user
backends.
## What this role does
- Renders the Compose stack with traefik labels and TLS
- Installs and enables a configurable list of Nextcloud apps idempotently
- Configures Collabora (richdocuments), draw.io, OIDC providers and
LDAP via `occ` — every setting is read first and only written when
the stored value differs, so re-runs don't churn
- Sets up notify_push (when enabled)
- Applies an in-container PHP source workaround for the upstream
`UserConfig::getValueBool` TypeError on Nextcloud 33.0.3 (idempotent
via grep guard; remove the patch task once the deployed image
ships the upstream fix)
## Requirements
- Docker and Docker Compose installed on the target host
- Ansible collection: `community.docker`
- Traefik with a shared `nextcloud_traefik_network` (default `proxy`)
## Role variables
Full spec with types and defaults: `meta/argument_specs.yml`. The most
common overrides:
### Service
- `nextcloud_domains`: FQDNs the router accepts. First entry is the
canonical hostname (used for `OVERWRITEHOST` and notify_push setup).
Further entries cover internal `*.int.*` names so Collabora's WOPI
callback hits the instance on a name with a valid cert.
- `nextcloud_admin_password`, `nextcloud_postgres_password` (required).
- `nextcloud_memory_limit_mb`, `nextcloud_upload_limit_mb`.
### Collabora
- `nextcloud_enable_collabora`: toggle integration with a separately
deployed Collabora server (see the `collabora` role).
- `nextcloud_collabora_domain`: server-to-server hostname.
- `nextcloud_collabora_public_domain` (optional): browser-facing
hostname when split-horizon uses different names.
### Draw.io
- `nextcloud_enable_drawio`: enable the `integration_drawio` app.
- `nextcloud_drawio_url`: public draw.io URL.
- `nextcloud_drawio_theme`, `nextcloud_drawio_offline`.
### Notify push
- `nextcloud_enable_notify_push`: deploy the notify_push companion.
- `nextcloud_notify_push_domain` (optional): override the hostname
used by `occ notify_push:setup` to avoid hairpinning through the DMZ.
### S3 primary storage
Set `nextcloud_use_s3_storage: true` plus the `nextcloud_s3_*` block to
point Nextcloud at an external S3-compatible store (e.g. Garage, MinIO).
### OIDC
`nextcloud_oidc_providers` is a list of OIDC providers registered with
`user_oidc`. Required fields per entry: `identifier`, `display_name`,
`client_id`, `client_secret`, `discovery_url`.
### LDAP
Set `nextcloud_ldap_enabled: true` and provide `nextcloud_ldap_config`
as a dict of `occ ldap:set-config s01 KEY VALUE` pairs. The role reads
the current LDAP config via `occ ldap:show-config s01 --output=json`
and only calls `ldap:set-config` for keys whose stored value differs.
## Dependencies
- Traefik network (`nextcloud_traefik_network`, default `proxy`)
- Optional: `collabora`, `drawio`, `garage` roles for the corresponding
integrations
- Optional: an OIDC provider (Keycloak, authentik) reachable from
Nextcloud and a 389ds LDAP server when using `user_ldap`
## Example playbook
```yaml
- hosts: app_servers
roles:
- role: digitalboard.core.nextcloud
vars:
nextcloud_domains:
- "cloud.example.com"
- "cloud.int.example.com"
nextcloud_admin_password: "{{ vault_nextcloud_admin_password }}"
nextcloud_postgres_password: "{{ vault_nextcloud_pg_password }}"
nextcloud_enable_collabora: true
nextcloud_collabora_domain: "office.int.example.com"
nextcloud_collabora_public_domain: "office.example.com"
nextcloud_enable_notify_push: true
nextcloud_notify_push_domain: "cloud.int.example.com"
nextcloud_oidc_providers:
- identifier: authentik
display_name: "Login with Authentik"
client_id: nextcloud
client_secret: "{{ vault_nextcloud_oidc_secret }}"
discovery_url: "https://auth.example.com/application/o/nextcloud/.well-known/openid-configuration"
mapping:
uid: preferred_username
display_name: name
email: email
groups: groups
```
## License
MIT-0