Simon Bärlocher 14c81657d7

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.

2026-05-26 14:16:47 +02:00

4.3 KiB

Raw Blame History

Nextcloud

Ansible role to deploy Nextcloud (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

- 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

4.3 KiB Raw Blame History