Simon Bärlocher 03bf0efe44

docs(collection): document all roles and fix metadata drift

Replace ansible-galaxy init placeholders across the collection and
correct documentation that drifted from the code, after a multi-agent
review of every role README against its defaults, tasks and templates.

Collection level:
- README: role table for all 16 roles, requirements and role-ordering
- galaxy.yml: declare community.docker and community.general deps,
  real description/tags/urls; normalize license to MIT-0
- meta/runtime.yml: requires_ansible '>=2.15.0'
- plugins/README: document the homarr_layout filter and
  garage_credentials lookup instead of scaffold boilerplate

Per-role meta/main.yml and README for the placeholder roles
(389ds, authentik, authentik_outpost_ldap, base, collabora, drawio,
garage, homarr, httpbin, keycloak, nextcloud, opencloud, traefik).

Correctness fixes found during review:
- keycloak: wrong domain default, drop invented keycloak_cert_resolver,
  document the provisioning feature
- garage: root_domain is .s3.<first-entry>, not the bare domain
- opnform: jwt/front_api secrets use `openssl rand -hex 32`; align the
  validation fail_msg in tasks/main.yml accordingly
- send: S3 example references garage_s3_domains[0] (was singular)
- opencloud: document required opencloud_wopi_domain

License normalized to MIT-0 across galaxy.yml, role meta and READMEs to
match the SPDX headers.

2026-05-27 22:33:42 +02:00

4.4 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 (nextcloud/server#59629, fixed in master via PR #59646 with no stable33 backport before 33.0.4). Idempotent via grep guard; remove the patch task once nextcloud_image is >= 33.0.4.

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.4 KiB Raw Blame History