Simon Bärlocher 3236ca332f

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 23:12:24 +02:00

3.8 KiB

Raw Blame History

Ansible Collection — digitalboard.core

This collection bundles the Ansible roles used to deploy the Digitalboard platform: a set of self-hosted, Docker-Compose-based services running behind Traefik, with single sign-on provided by authentik or Keycloak.

Each role provisions one service (or building block) as a self-contained Docker Compose stack. Roles are consumed from the deployment repository reference-ansible, where inventories and playbooks tie the roles to concrete hosts.

Roles

Role	Description
`base`	Host baseline: Docker, apt packages and convenience tooling on Debian/Ubuntu.
`traefik`	Traefik v3 reverse proxy as a public DMZ proxy (file provider) or backend proxy (docker provider).
`authentik`	authentik IdP (server + worker + Postgres); resources via blueprints.
`authentik_outpost_ldap`	authentik LDAP outpost exposing an LDAP interface for apps that cannot speak OIDC.
`keycloak`	Keycloak IdP with a PostgreSQL backend.
`389ds`	389 Directory Server LDAP directory via Docker Compose.
`nextcloud`	Nextcloud (fpm) + Postgres + Redis, optional Collabora/draw.io/notify_push.
`opencloud`	OpenCloud file platform via Docker Compose.
`collabora`	Collabora Online (CODE), used as the WOPI backend for Nextcloud.
`bookstack`	BookStack wiki (LSIO + MariaDB) with OIDC SSO and daily backups.
`drawio`	draw.io diagram editor, with optional authentik ForwardAuth gating.
`homarr`	Homarr dashboard with seeded admin user and OIDC group.
`opnform`	OpnForm self-hosted form builder (api + ui + db + redis).
`send`	Send (timvisee fork) file sharing with a Redis backend.
`garage`	Garage S3-compatible object storage with key/bucket provisioning.
`httpbin`	httpbin HTTP request/response testing service for validating Traefik ingress.

Usage

Roles are not run from this repository directly. They are consumed from the deployment repository reference-ansible, which holds the inventories, group/host variables and playbooks. See that repository's docs/ directory for getting-started instructions, how to run Ansible and how secrets are managed.

Per-role variables and their defaults are documented in each role's own README.md and meta/argument_specs.yml.

Requirements

A Debian/Ubuntu target host (the base role bootstraps Docker there).
ansible-core 2.15 or newer on the controller.
The community.docker collection (used by nearly every role) and community.general (used by the keycloak role). Both are declared as dependencies in galaxy.yml and pulled in automatically when this collection is installed via ansible-galaxy.

The role READMEs use community.hashi_vault lookups in their examples to source secrets from HashiCorp Vault. That is a documented convention, not a hard dependency of the roles — supply the variables however you prefer.

Role ordering

Within a play, apply the roles in dependency order: base first (Docker and the host baseline), then traefik (the shared reverse proxy and its Docker network), then the individual service roles (authentik, keycloak, nextcloud, …), which attach to Traefik's network and expect Docker to be present.

License

MIT-0. See individual roles for per-role license metadata.

3.8 KiB Raw Blame History