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:
parent
a9c33baed9
commit
1dcff92240
10 changed files with 1348 additions and 143 deletions
123
roles/nextcloud/README.md
Normal file
123
roles/nextcloud/README.md
Normal 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
|
||||
Loading…
Add table
Add a link
Reference in a new issue