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
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
|
||||
253
roles/nextcloud/meta/argument_specs.yml
Normal file
253
roles/nextcloud/meta/argument_specs.yml
Normal file
|
|
@ -0,0 +1,253 @@
|
|||
---
|
||||
argument_specs:
|
||||
main:
|
||||
short_description: Deploy Nextcloud (fpm) + Redis + Postgres via Docker Compose.
|
||||
description:
|
||||
- Renders a Compose stack for Nextcloud with traefik labels, optional
|
||||
Collabora WOPI integration, optional draw.io integration, optional
|
||||
notify_push companion, optional S3 primary storage, OIDC providers
|
||||
and LDAP user backend.
|
||||
- "All C(occ)-driven configuration tasks are idempotent: each setting
|
||||
is read with C(config:app:get) (or C(ldap:show-config)) first and
|
||||
only written when the stored value differs."
|
||||
options:
|
||||
docker_compose_base_dir:
|
||||
type: path
|
||||
default: /etc/docker/compose
|
||||
docker_volume_base_dir:
|
||||
type: path
|
||||
default: /srv/data
|
||||
nextcloud_service_name:
|
||||
type: str
|
||||
default: nextcloud
|
||||
nextcloud_docker_compose_dir:
|
||||
type: path
|
||||
nextcloud_docker_volume_dir:
|
||||
type: path
|
||||
|
||||
nextcloud_domains:
|
||||
type: list
|
||||
elements: str
|
||||
default: ['nextcloud.local.test']
|
||||
description:
|
||||
- FQDNs the nextcloud router accepts. The first entry is the
|
||||
canonical domain (used for C(OVERWRITEHOST) and the
|
||||
C(notify_push) setup). Further entries cover internal C(*.int.*)
|
||||
names so Collabora's WOPI callback hits the instance on a name
|
||||
with a valid certificate.
|
||||
nextcloud_image:
|
||||
type: str
|
||||
default: nextcloud:fpm
|
||||
nextcloud_redis_image:
|
||||
type: str
|
||||
default: redis:latest
|
||||
nextcloud_port:
|
||||
type: int
|
||||
default: 80
|
||||
nextcloud_extra_hosts:
|
||||
type: list
|
||||
elements: str
|
||||
default: []
|
||||
nextcloud_extra_networks:
|
||||
type: list
|
||||
elements: str
|
||||
default: []
|
||||
nextcloud_allow_local_remote_servers:
|
||||
type: bool
|
||||
default: false
|
||||
description: Allow requests to local network from Nextcloud (dev only).
|
||||
|
||||
nextcloud_postgres_image:
|
||||
type: str
|
||||
default: postgres:15
|
||||
nextcloud_postgres_db:
|
||||
type: str
|
||||
default: nextcloud
|
||||
nextcloud_postgres_user:
|
||||
type: str
|
||||
default: nextcloud
|
||||
nextcloud_postgres_password:
|
||||
type: str
|
||||
required: true
|
||||
|
||||
nextcloud_backend_network:
|
||||
type: str
|
||||
default: nextcloud-internal
|
||||
nextcloud_traefik_network:
|
||||
type: str
|
||||
default: proxy
|
||||
nextcloud_use_ssl:
|
||||
type: bool
|
||||
default: true
|
||||
|
||||
nextcloud_enable_collabora:
|
||||
type: bool
|
||||
default: true
|
||||
nextcloud_collabora_domain:
|
||||
type: str
|
||||
default: office.local.test
|
||||
description: Hostname Nextcloud uses to talk to Collabora server-to-server.
|
||||
nextcloud_collabora_public_domain:
|
||||
type: str
|
||||
description:
|
||||
- Optional browser-facing hostname for Collabora; defaults to
|
||||
C(nextcloud_collabora_domain) when unset. Set when split-horizon
|
||||
uses different names for browser and server traffic.
|
||||
nextcloud_collabora_disable_cert_verification:
|
||||
type: bool
|
||||
default: false
|
||||
|
||||
nextcloud_enable_drawio:
|
||||
type: bool
|
||||
default: false
|
||||
description: Enable the integration_drawio Nextcloud app and configure the URL/theme.
|
||||
nextcloud_drawio_url:
|
||||
type: str
|
||||
default: ''
|
||||
description: Public draw.io URL used by the integration_drawio app.
|
||||
nextcloud_drawio_theme:
|
||||
type: str
|
||||
choices: [kennedy, atlas, dark, sketch, min]
|
||||
default: kennedy
|
||||
nextcloud_drawio_offline:
|
||||
type: str
|
||||
choices: ['yes', 'no']
|
||||
default: 'yes'
|
||||
|
||||
nextcloud_use_s3_storage:
|
||||
type: bool
|
||||
default: false
|
||||
description: Use S3 primary object storage instead of the local data dir.
|
||||
nextcloud_s3_key:
|
||||
type: str
|
||||
default: changeme
|
||||
nextcloud_s3_secret:
|
||||
type: str
|
||||
default: changeme
|
||||
nextcloud_s3_region:
|
||||
type: str
|
||||
default: us-east-1
|
||||
nextcloud_s3_bucket:
|
||||
type: str
|
||||
default: nextcloud
|
||||
nextcloud_s3_host:
|
||||
type: str
|
||||
default: s3.example.com
|
||||
nextcloud_s3_port:
|
||||
type: int
|
||||
default: 443
|
||||
nextcloud_s3_ssl:
|
||||
type: bool
|
||||
default: true
|
||||
nextcloud_s3_usepath_style:
|
||||
type: bool
|
||||
default: true
|
||||
nextcloud_s3_autocreate:
|
||||
type: bool
|
||||
default: false
|
||||
|
||||
nextcloud_admin_user:
|
||||
type: str
|
||||
default: admin
|
||||
nextcloud_admin_password:
|
||||
type: str
|
||||
required: true
|
||||
nextcloud_memory_limit_mb:
|
||||
type: int
|
||||
default: 1024
|
||||
nextcloud_upload_limit_mb:
|
||||
type: int
|
||||
default: 2048
|
||||
nextcloud_scale_factor:
|
||||
type: int
|
||||
default: 2
|
||||
|
||||
nextcloud_trusted_proxies:
|
||||
type: str
|
||||
default: '172.16.0.0/12'
|
||||
description: Trusted proxy CIDR(s) — by default the Docker internal range.
|
||||
|
||||
nextcloud_enable_notify_push:
|
||||
type: bool
|
||||
default: false
|
||||
nextcloud_notify_push_image:
|
||||
type: str
|
||||
default: icewind1991/notify_push:1.3.1
|
||||
nextcloud_notify_push_domain:
|
||||
type: str
|
||||
description:
|
||||
- Hostname used when calling C(occ notify_push:setup). Defaults to
|
||||
the first C(nextcloud_domains) entry. Override with an internal
|
||||
FQDN to avoid hairpinning the setup check through the DMZ; the
|
||||
FQDN must also be in C(nextcloud_domains).
|
||||
|
||||
nextcloud_apps_to_install:
|
||||
type: list
|
||||
elements: str
|
||||
default:
|
||||
- groupfolders
|
||||
- richdocuments
|
||||
- spreed
|
||||
- user_ldap
|
||||
- user_oidc
|
||||
- whiteboard
|
||||
- files_lock
|
||||
- notify_push
|
||||
description:
|
||||
- Non-default Nextcloud apps to install + enable.
|
||||
Install/enable detection is idempotent — re-runs report C(ok)
|
||||
when the app is already present and enabled.
|
||||
|
||||
nextcloud_oidc_allow_selfsigned:
|
||||
type: bool
|
||||
default: false
|
||||
nextcloud_oidc_providers:
|
||||
type: list
|
||||
elements: dict
|
||||
default: []
|
||||
description: OIDC providers registered with the user_oidc app.
|
||||
options:
|
||||
identifier:
|
||||
type: str
|
||||
required: true
|
||||
display_name:
|
||||
type: str
|
||||
required: true
|
||||
client_id:
|
||||
type: str
|
||||
required: true
|
||||
client_secret:
|
||||
type: str
|
||||
required: true
|
||||
discovery_url:
|
||||
type: str
|
||||
required: true
|
||||
scope:
|
||||
type: str
|
||||
default: openid email profile
|
||||
unique_uid:
|
||||
type: bool
|
||||
default: true
|
||||
check_bearer:
|
||||
type: bool
|
||||
default: false
|
||||
send_id_token_hint:
|
||||
type: bool
|
||||
default: true
|
||||
mapping:
|
||||
type: dict
|
||||
nextcloud_oidc_providers_removed:
|
||||
type: list
|
||||
elements: str
|
||||
default: []
|
||||
|
||||
nextcloud_ldap_enabled:
|
||||
type: bool
|
||||
default: false
|
||||
nextcloud_ldap_config:
|
||||
type: dict
|
||||
default: {}
|
||||
description:
|
||||
- Key/value pairs passed to C(occ ldap:set-config s01 KEY VALUE).
|
||||
The role reads the current config first and only invokes
|
||||
C(set-config) when a stored value differs.
|
||||
Loading…
Add table
Add a link
Reference in a new issue