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.
This commit is contained in:
Simon Bärlocher 2026-05-27 22:33:42 +02:00
parent 19864d79b2
commit 3236ca332f
No known key found for this signature in database
GPG key ID: 63DE20495932047A
38 changed files with 740 additions and 625 deletions

View file

@ -1,31 +1,32 @@
# Collections Plugins Directory
# Collection Plugins — digitalboard.core
This directory can be used to ship various plugins inside an Ansible collection. Each plugin is placed in a folder that
is named after the type of plugin it is in. It can also include the `module_utils` and `modules` directory that
would contain module utils and modules respectively.
This collection ships a small number of custom plugins that support the roles.
They are addressed by their fully qualified name, `digitalboard.core.<name>`.
Here is an example directory of the majority of plugins currently supported by Ansible:
## Filter plugins (`filter/`)
```
└── plugins
├── action
├── become
├── cache
├── callback
├── cliconf
├── connection
├── filter
├── httpapi
├── inventory
├── lookup
├── module_utils
├── modules
├── netconf
├── shell
├── strategy
├── terminal
├── test
└── vars
`homarr_layout` — computes Homarr dashboard grid layouts (desktop / tablet /
mobile breakpoints) from a list of apps, returning a ready-to-render data
structure for the SQL seed. Used by the `homarr` role.
```yaml
- name: Compute Homarr app layouts
ansible.builtin.set_fact:
homarr_layout: "{{ homarr_apps | digitalboard.core.homarr_compute_layouts }}"
```
A full list of plugin types can be found at [Working With Plugins](https://docs.ansible.com/ansible-core/2.19/plugins/plugins.html).
## Lookup plugins (`lookup/`)
`garage_credentials` — returns S3 credentials (`key_id`, `secret_key`) for a
named Garage key by executing a docker command on the target host. Used to wire
Garage object storage into consuming roles such as `nextcloud`.
```yaml
nextcloud_s3_key: >-
{{ lookup('digitalboard.core.garage_credentials', 'nextcloud', host='backend')['key_id'] }}
nextcloud_s3_secret: >-
{{ lookup('digitalboard.core.garage_credentials', 'nextcloud', host='backend')['secret_key'] }}
```
No other plugin types (modules, action, callback, inventory, etc.) are currently
shipped by this collection.