Digitalboard/digitalboard.core
6
2
Fork 0
Code Pull requests 1 Releases Packages Activity Actions

docs(roles): add argument_specs and README for traefik, authentik, drawio, garage, nextcloud

Browse source 
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 2026-05-26 14:16:47 +02:00
parent a9c33baed9
commit 1dcff92240
No known key found for this signature in database
GPG key ID: 63DE20495932047A
10 changed files with 1348 additions and 143 deletions
Download patch file Download diff file Expand all files Collapse all files

117
roles/authentik/README.md
View file

@ -1,28 +1,131 @@
# Authentik
Deploys Authentik identity provider with Docker Compose.
Deploys [authentik](https://goauthentik.io) (server + worker + Postgres)
as a Docker Compose stack behind Traefik, with all resources provisioned
via templated blueprints.
## What this role does
- Renders the Compose stack with traefik labels and an optional
split-horizon host rewrite (see below)
- Provisions local users, groups, OIDC apps, Proxy/ForwardAuth apps,
LDAP apps and outposts, and Entra ID OAuth sources via blueprints
- Configures the login screen (visible sources, local login fields)
- Supports declarative cleanup via `authentik_removed_*` lists
## Variables
See `defaults/main.yml` for all available variables.
Full spec with types and defaults: `meta/argument_specs.yml`. The most
common overrides:
## Blueprints
### Service
- `authentik_domains` (required, list): FQDNs the router accepts. First
entry is the canonical hostname; further entries cover internal
`*.int.*` names for server-to-server traffic.
- `authentik_secret_key` (required): PG fernet / signing secret.
Generate with `openssl rand -base64 60`.
- `authentik_postgres_password` (required).
- `authentik_image`, `authentik_port`, `authentik_log_level`.
### Split-horizon host rewrite
`authentik_host_rewrite_domains` lists hostnames that should reach the
authentik container but make it generate URLs (OIDC issuer, password
reset links, etc.) as if the request had arrived on
`authentik_domains[0]`.
For each entry the role:
- Creates a dedicated traefik router on that hostname
- Routes it to a URL-based loadbalancer service that disables
`passHostHeader`, so the upstream Host header becomes the canonical
FQDN
- Pins `X-Forwarded-Host` via middleware so the iss claim stays aligned
with the public hostname browsers see
Use case: an internal `auth.int.example.com` keeps server-to-server
traffic in the LAN, but Keycloak/Nextcloud/etc. still receive issuer
URLs matching `auth.example.com`.
### Blueprints
The role renders blueprints for:
- Local users (`authentik_local_users`)
- Groups (`authentik_groups`)
- OIDC applications (`authentik_oidc_apps`)
- Proxy applications (`authentik_proxy_apps`)
- Proxy outposts (`authentik_proxy_outposts`)
- LDAP applications (`authentik_ldap_apps`)
- LDAP outpost (`authentik_ldap_outpost`)
- Entra ID sources (`authentik_entra_sources`)
- Login screen sources (`authentik_login_source_ids`)
- Login-screen source visibility (`authentik_login_sources`)
Secrets are passed via `authentik_blueprint_env` using environment variable references.
Secrets are passed via the `authentik_blueprint_env` env-var indirection
so they never land in rendered blueprint YAML on disk.
#### Proxy apps: mode and group restrictions
Each entry in `authentik_proxy_apps` supports:
- `mode` (default `forward_single`): one of `proxy`, `forward_single`,
`forward_domain`
- `allowed_groups`: when set, a `PolicyBinding` is emitted per group on
the application. authentik OR-evaluates bindings, so users in any
listed group pass and users in none are denied.
Example:
```yaml
authentik_proxy_apps:
- slug: drawio
name: drawio
external_host: "https://drawio.example.com"
mode: forward_single
allowed_groups:
- drawio-users
- admins
```
## Removing resources
To remove resources from Authentik, move slugs to the removal lists:
Move slugs from the active list to the matching removal list:
- `authentik_removed_oidc_apps`
- `authentik_removed_proxy_apps`
- `authentik_removed_local_users`
After confirming deletion, remove the slug from the list.
After authentik has applied the deletion blueprint, remove the slug
from the list to keep state clean.
## Dependencies
- Traefik network (`authentik_traefik_network`, default `proxy`)
- Internal backend network (`authentik_backend_network`, default `backend`)
## Example playbook
```yaml
- hosts: identity_servers
roles:
- role: digitalboard.core.authentik
vars:
authentik_domains:
- "auth.example.com"
- "auth.int.example.com"
authentik_host_rewrite_domains:
- "auth.int.example.com"
authentik_secret_key: "{{ vault_authentik_secret_key }}"
authentik_postgres_password: "{{ vault_authentik_pg_password }}"
authentik_proxy_apps:
- slug: drawio
name: drawio
external_host: "https://drawio.example.com"
mode: forward_single
allowed_groups: [drawio-users]
```
## License
MIT-0

193
roles/authentik/meta/argument_specs.yml Normal file
View file

@ -0,0 +1,193 @@
---
argument_specs:
main:
short_description: Deploy authentik (server + worker + Postgres) via Docker Compose.
description:
- Renders a Compose stack for authentik with traefik labels, optional
TLS and a configurable split-horizon host-rewrite that keeps the OIDC
issuer URL on the canonical public hostname even when traffic enters
on an internal FQDN.
- Provisions resources through templated blueprints
(local users, groups, OIDC/Proxy/LDAP apps, outposts, OAuth sources).
options:
docker_compose_base_dir:
type: path
default: /etc/docker/compose
docker_volume_base_dir:
type: path
default: /srv/data
authentik_service_name:
type: str
default: authentik
authentik_docker_compose_dir:
type: path
description: Defaults to C({{ docker_compose_base_dir }}/{{ authentik_service_name }}).
authentik_docker_volume_dir:
type: path
description: Defaults to C({{ docker_volume_base_dir }}/{{ authentik_service_name }}).
authentik_domains:
type: list
elements: str
required: true
description:
- FQDNs the authentik router accepts. The first entry is the
canonical (public) hostname and is used for the network alias,
the X-Forwarded-Host rewrite target, and as the default OIDC
issuer. Further entries cover internal C(*.int.*) names used
for server-to-server traffic.
authentik_host_rewrite_domains:
type: list
elements: str
default: []
description:
- Hostnames that should reach authentik but make it generate URLs
(OIDC issuer, password reset links, etc.) as if the request had
arrived on C(authentik_domains[0]).
- Each entry gets its own traefik router and a URL-based
loadbalancer service that disables passHostHeader and pins
X-Forwarded-Host via middleware. Used for split-horizon setups
where the LAN keeps server-to-server traffic but the iss claim
must match the public hostname browsers see.
authentik_image:
type: str
default: ghcr.io/goauthentik/server:2026.2.2
authentik_port:
type: int
default: 9000
authentik_secret_key:
type: str
required: true
description: PG fernet key / signing secret. Generate with C(openssl rand -base64 60).
authentik_postgres_image:
type: str
default: postgres:16-alpine
authentik_postgres_db:
type: str
default: authentik
authentik_postgres_user:
type: str
default: authentik
authentik_postgres_password:
type: str
required: true
authentik_traefik_network:
type: str
default: proxy
authentik_backend_network:
type: str
default: backend
authentik_use_ssl:
type: bool
default: true
authentik_log_level:
type: str
choices: [trace, debug, info, warning, error]
default: info
authentik_error_reporting_enabled:
type: bool
default: false
authentik_proxy_apps:
type: list
elements: dict
default: []
description:
- Proxy/ForwardAuth applications rendered via the
C(blueprint-proxy-app.yaml.j2) template.
options:
slug:
type: str
required: true
name:
type: str
required: true
internal_host:
type: str
description: Required when C(mode=proxy).
external_host:
type: str
required: true
mode:
type: str
choices: [proxy, forward_single, forward_domain]
default: forward_single
description:
- "C(proxy): the outpost itself proxies traffic to internal_host."
- "C(forward_single): a single app behind an external reverse
proxy via ForwardAuth."
- "C(forward_domain): wildcard mode — one provider guards every
host on a cookie domain."
allowed_groups:
type: list
elements: str
description:
- If set, PolicyBindings are emitted (one per group, OR-evaluated).
Users in none of the listed groups are denied.
skip_path_regex:
type: str
flows:
type: dict
description: Authentication / authorization / invalidation flow slugs.
authentik_proxy_outposts:
type: list
elements: dict
default: []
authentik_ldap_apps:
type: list
elements: dict
default: []
authentik_ldap_outpost:
type: dict
default: {}
authentik_oidc_apps:
type: list
elements: dict
default: []
authentik_entra_sources:
type: list
elements: dict
default: []
authentik_login_sources:
type: list
elements: dict
default: []
authentik_identification_stage_name:
type: str
default: default-authentication-identification
authentik_login_user_fields:
type: list
elements: str
choices: [username, email, upn]
default: [username, email]
description: Local login fields shown on the login screen. Empty list hides local login.
authentik_groups:
type: list
elements: dict
default: []
authentik_local_users:
type: list
elements: dict
default: []
authentik_removed_oidc_apps:
type: list
elements: str
default: []
description: OIDC application slugs scheduled for deletion.
authentik_removed_proxy_apps:
type: list
elements: str
default: []
authentik_removed_local_users:
type: list
elements: str
default: []

70
roles/drawio/README.md
View file

@ -1,38 +1,60 @@
Role Name
=========
# Drawio
A brief description of the role goes here.
Ansible role to deploy [draw.io](https://www.drawio.com/) (the
self-hosted `jgraph/drawio` container) via Docker Compose behind
Traefik, with optional authentik ForwardAuth gating.
Requirements
------------
## Requirements
Any pre-requisites that may not be covered by Ansible itself or the role should be mentioned here. For instance, if the role uses the EC2 module, it may be a good idea to mention in this section that the boto package is required.
- Docker and Docker Compose installed on the target host
- Ansible collection: `community.docker`
- Traefik with a shared `drawio_traefik_network` (default `proxy`)
- For ForwardAuth: a reachable authentik embedded outpost endpoint
Role Variables
--------------
## Role variables
A description of the settable variables for this role should go here, including any variables that are in defaults/main.yml, vars/main.yml, and any variables that can/should be set via parameters to the role. Any variables that are read from other roles and/or the global scope (ie. hostvars, group vars, etc.) should be mentioned here as well.
Full spec with types and defaults: `meta/argument_specs.yml`. The most
common overrides:
Dependencies
------------
### Service
A list of other roles hosted on Galaxy should go here, plus any details in regards to parameters that may need to be set for other roles, or variables that are used from other roles.
- `drawio_domain`: canonical hostname used in the traefik Host rule
(default `drawio.local.test`).
- `drawio_extra_domains`: additional hostnames the same container
should answer on (e.g. an internal `*.int.*` FQDN so a DMZ proxy
can reach drawio via a backend hostname).
- `drawio_image`, `drawio_port`, `drawio_use_ssl`.
Example Playbook
----------------
### Authentik ForwardAuth
Including an example of how to use your role (for instance, with variables passed in as parameters) is always nice for users too:
- `drawio_authentik_forward_auth`: set to `true` to gate the editor
behind authentik.
- `drawio_authentik_forward_auth_url`: full URL of the embedded
outpost ForwardAuth endpoint, e.g.
`https://auth.example.com/outpost.goauthentik.io/auth/traefik`.
- hosts: servers
roles:
- { role: username.rolename, x: 42 }
When enabled, traefik redirects unauthenticated requests to authentik
for login and forwards the resulting `X-Authentik-*` identity headers
downstream.
License
-------
## Dependencies
BSD
- Traefik network (`drawio_traefik_network`, default `proxy`)
- Optional: authentik with a Proxy/ForwardAuth provider for drawio
(see the `authentik` role's `authentik_proxy_apps`).
Author Information
------------------
## Example playbook
An optional section for the role authors to include contact information, or a website (HTML is not allowed).
```yaml
- hosts: app_servers
roles:
- role: digitalboard.core.drawio
vars:
drawio_domain: "drawio.example.com"
drawio_authentik_forward_auth: true
drawio_authentik_forward_auth_url: "https://auth.example.com/outpost.goauthentik.io/auth/traefik"
```
## License
MIT-0

64
roles/drawio/meta/argument_specs.yml Normal file
View file

@ -0,0 +1,64 @@
---
argument_specs:
main:
short_description: Deploy draw.io diagram editor via Docker Compose behind Traefik.
description:
- Renders a Compose stack for jgraph/drawio with traefik labels, optional
TLS and optional authentik ForwardAuth gating.
options:
docker_compose_base_dir:
type: path
default: /etc/docker/compose
drawio_service_name:
type: str
default: drawio
drawio_docker_compose_dir:
type: path
description: Defaults to C({{ docker_compose_base_dir }}/{{ drawio_service_name }}).
drawio_domain:
type: str
default: drawio.local.test
description: Canonical hostname used in the traefik Host rule.
drawio_extra_domains:
type: list
elements: str
default: []
description:
- Additional hostnames the same drawio container should answer on,
e.g. an internal C(*.int.*) FQDN so a DMZ reverse-proxy can reach
drawio via a backend hostname covered by the local traefik cert.
drawio_image:
type: str
default: jgraph/drawio:latest
drawio_port:
type: int
default: 8080
drawio_extra_hosts:
type: list
elements: str
default: []
description: C(extra_hosts) entries injected into the container (Docker C(host:ip) syntax).
drawio_traefik_network:
type: str
default: proxy
drawio_use_ssl:
type: bool
default: true
drawio_authentik_forward_auth:
type: bool
default: false
description:
- When true, traefik attaches a ForwardAuth middleware pointing at
the authentik embedded outpost. Unauthenticated requests are
redirected to authentik for login and the resulting
C(X-Authentik-*) identity headers are forwarded downstream.
drawio_authentik_forward_auth_url:
type: str
default: ''
description:
- URL of the authentik ForwardAuth endpoint, typically
C(https://auth.example.com/outpost.goauthentik.io/auth/traefik).
Required when C(drawio_authentik_forward_auth=true).

179
roles/garage/README.md
View file

@ -1,113 +1,116 @@
Garage
======
# Garage
Ansible role to deploy Garage S3-compatible object storage using Docker Compose.
Ansible role to deploy [Garage](https://garagehq.deuxfleurs.fr/) S3-compatible
object storage via Docker Compose, with declarative key/bucket
provisioning and an optional WebUI behind htpasswd or authentik
ForwardAuth.
Requirements
------------
## Requirements
- Docker and Docker Compose installed on the target host
- Ansible collection: `community.docker`
- Traefik reverse proxy (for external access)
- `htpasswd` (from `apache2-utils` / `httpd-tools`) when the WebUI is
enabled and authentik ForwardAuth is *not* used
- Traefik with a shared `garage_traefik_network` (default `proxy`)
Role Variables
--------------
## Role variables
Key variables defined in `defaults/main.yml`:
Full spec with types and defaults: `meta/argument_specs.yml`. The most
common overrides:
**Base Configuration:**
- `docker_compose_base_dir`: Base directory for Docker Compose files (default: `/etc/docker/compose`)
- `docker_volume_base_dir`: Base directory for Docker volumes (default: `/srv/data`)
### Service
**Garage Configuration:**
- `garage_service_name`: Service name (default: `garage`)
- `garage_image`: Garage Docker image (default: `dxflrs/garage:v2.1.0`)
- `garage_s3_domain`: Domain for S3 API endpoint (default: `storage.local.test`)
- `garage_web_domain`: Domain for S3 web endpoint (default: `web.storage.local.test`)
- `garage_webui_domain`: Domain for web console (default: `console.storage.local.test`)
- `garage_s3_domains`: FQDNs the S3 router accepts. First entry is the
canonical hostname and is used as `root_domain` in `garage.toml`.
- `garage_web_domain`, `garage_webui_domain`: separate hostnames for
the S3-website endpoint and the console.
- `garage_image`, `garage_replication_factor`, `garage_db_engine`,
`garage_s3_region`.
**Garage Storage Configuration:**
- `garage_replication_factor`: Replication factor (default: `1`)
- `garage_compression_level`: Compression level (default: `1`)
- `garage_db_engine`: Database engine (default: `lmdb`)
- `garage_s3_region`: S3 region (default: `us-east-1`)
### Required secrets
**Garage Ports:**
- `garage_s3_api_port`: S3 API port (default: `3900`)
- `garage_s3_web_port`: S3 web port (default: `3902`)
- `garage_admin_port`: Admin API port (default: `3903`)
- `garage_rpc_port`: RPC port (default: `3901`)
Generate with `openssl rand -hex 32` (32 bytes / 64 hex chars):
**Garage Security:**
- `garage_rpc_secret`: RPC secret for node communication
- `garage_admin_token`: Admin API token
- `garage_metrics_token`: Metrics API token
- `garage_rpc_secret`: node-to-node RPC secret
- `garage_admin_token`: admin API token
- `garage_metrics_token`: metrics endpoint token
**Garage WebUI Configuration:**
- `garage_webui_enabled`: Enable web UI (default: `true`)
- `garage_webui_image`: WebUI Docker image (default: `khairul169/garage-webui:latest`)
- `garage_webui_port`: WebUI port (default: `3909`)
- `garage_webui_username`: WebUI username (default: `admin`)
- `garage_webui_password`: WebUI password in plaintext (default: `admin`)
### WebUI authentication
**Traefik Configuration:**
- `garage_traefik_network`: Traefik network name (default: `proxy`)
- `garage_internal_network`: Internal network name (default: `internal`)
- `garage_use_ssl`: Enable SSL (default: `true`)
Three modes:
Dependencies
------------
1. **htpasswd** (default): `garage_webui_username` / `garage_webui_password`
in plaintext. The role hashes the password with
`htpasswd -nbBC 10`, persists the hash on disk, and re-verifies with
`htpasswd -vbB` so unchanged passwords don't churn the play.
2. **authentik ForwardAuth**: set
`garage_webui_authentik_forward_auth: true` and
`garage_webui_authentik_forward_auth_url:
"https://auth.example.com/outpost.goauthentik.io/auth/traefik"`.
`AUTH_USER_PASS` is dropped from the container env so authentik is
the only gate.
3. **Disabled**: `garage_webui_enabled: false`.
This role requires:
- Traefik reverse proxy to be configured and the `proxy` network to be created
- `htpasswd` utility (from `apache2-utils` package) for generating bcrypt password hashes
### Layout bootstrap
Example Playbook
----------------
Setting `garage_bootstrap_enabled: true` runs the bootstrap task, which
joins the local node to the layout (`zone: garage_bootstrap_zone`,
capacity: `garage_bootstrap_capacity`) on the first run. The check
tolerates the 16-char truncation that `garage layout show` performs.
### Declarative S3 keys and buckets
```yaml
garage_s3_keys:
- name: nextcloud
buckets:
- name: nextcloud-data
permissions: [read, write]
- name: backup
buckets:
- name: restic-prod
permissions: [read, write, owner]
```
The role:
- Lists existing keys (`garage key list`), creates missing ones
- Lists existing buckets (`garage bucket list`), creates missing ones
- Reads current permissions via `garage bucket info` and runs
`garage bucket allow` only when the current RWO flags for the key
don't already match the desired permissions
`stdout` parsing is hardened against ANSI escapes and interleaved INFO
log lines, so probe noise no longer produces spurious changes.
## Dependencies
- Traefik network (`garage_traefik_network`, default `proxy`)
- Internal network (`garage_internal_network`, default `internal`)
## Example playbook
```yaml
- hosts: storage_servers
roles:
- role: garage
- role: digitalboard.core.garage
vars:
garage_s3_domain: "storage.example.com"
garage_rpc_secret: "your-secure-rpc-secret"
garage_admin_token: "your-admin-token"
garage_webui_enabled: true
garage_webui_username: "admin"
garage_webui_password: "secure-password"
garage_s3_domains:
- "storage.example.com"
- "storage.int.example.com"
garage_rpc_secret: "{{ vault_garage_rpc_secret }}"
garage_admin_token: "{{ vault_garage_admin_token }}"
garage_metrics_token: "{{ vault_garage_metrics_token }}"
garage_bootstrap_enabled: true
garage_webui_authentik_forward_auth: true
garage_webui_authentik_forward_auth_url: "https://auth.example.com/outpost.goauthentik.io/auth/traefik"
garage_s3_keys:
- name: nextcloud
buckets:
- name: nextcloud-data
permissions: [read, write]
```
**Note:** The WebUI password is specified in plaintext and will be automatically hashed using bcrypt during deployment. The role uses `htpasswd` to generate a secure bcrypt hash that is then properly escaped for use in Docker Compose.
## License
Post-Installation
-----------------
After deployment, you need to configure the Garage cluster:
1. Connect to the node and get the node ID:
```bash
docker exec -ti garage /garage node id
```
2. Configure the node layout:
```bash
docker exec -ti garage /garage layout assign -z dc1 -c 1G <node-id>
docker exec -ti garage /garage layout apply --version 1
```
3. Create a key for S3 access:
```bash
docker exec -ti garage /garage key create my-key
```
4. Create a bucket:
```bash
docker exec -ti garage /garage bucket create my-bucket
docker exec -ti garage /garage bucket allow my-bucket --read --write --key my-key
```
License
-------
MIT-0
MIT-0

169
roles/garage/meta/argument_specs.yml Normal file
View file

@ -0,0 +1,169 @@
---
argument_specs:
main:
short_description: Deploy Garage S3-compatible object storage via Docker Compose.
description:
- Renders a Compose stack for Garage with traefik labels, configures the
node layout on first run, and (optionally) provisions S3 keys, buckets
and per-key permissions declaratively.
- The optional WebUI can be protected by classic htpasswd or by
authentik ForwardAuth.
options:
docker_compose_base_dir:
type: path
default: /etc/docker/compose
docker_volume_base_dir:
type: path
default: /srv/data
garage_service_name:
type: str
default: garage
garage_docker_compose_dir:
type: path
description: Defaults to C({{ docker_compose_base_dir }}/{{ garage_service_name }}).
garage_docker_volume_dir:
type: path
description: Defaults to C({{ docker_volume_base_dir }}/{{ garage_service_name }}).
garage_image:
type: str
default: dxflrs/garage:v2.1.0
garage_s3_domains:
type: list
elements: str
default: ['storage.local.test']
description:
- FQDNs the garage S3 router accepts. The first entry is the
canonical domain and is used as the virtual-hosted-style
C(root_domain) in C(garage.toml). Further entries cover internal
C(*.int.*) names.
garage_web_domain:
type: str
default: web.storage.local.test
description: Hostname serving the S3-website endpoint.
garage_webui_domain:
type: str
default: console.storage.local.test
description: Hostname serving the WebUI console.
garage_webui_enabled:
type: bool
default: true
garage_webui_image:
type: str
default: khairul169/garage-webui:latest
garage_webui_port:
type: int
default: 3909
garage_webui_username:
type: str
default: admin
description: htpasswd username. Ignored when C(garage_webui_authentik_forward_auth=true).
garage_webui_password:
type: str
default: admin
description:
- Plaintext password; hashed with C(htpasswd -nbBC 10) and persisted
on disk so re-runs don't churn. Ignored when authentik ForwardAuth
is enabled.
garage_webui_authentik_forward_auth:
type: bool
default: false
description:
- When true the C(AUTH_USER_PASS) env-var is dropped from the WebUI
container and traefik attaches a ForwardAuth middleware pointing
at the URL below. authentik is then the only gate; htpasswd is
disabled.
garage_webui_authentik_forward_auth_url:
type: str
default: ''
description:
- Required when C(garage_webui_authentik_forward_auth=true).
Typically C(https://auth.example.com/outpost.goauthentik.io/auth/traefik).
garage_s3_api_port:
type: int
default: 3900
garage_s3_web_port:
type: int
default: 3902
garage_admin_port:
type: int
default: 3903
garage_rpc_port:
type: int
default: 3901
garage_replication_factor:
type: int
default: 1
garage_compression_level:
type: int
default: 1
garage_db_engine:
type: str
choices: [lmdb, sqlite, sled]
default: lmdb
garage_s3_region:
type: str
default: us-east-1
garage_rpc_secret:
type: str
required: true
description: Hex secret for node-to-node RPC. Generate with C(openssl rand -hex 32).
garage_admin_token:
type: str
required: true
garage_metrics_token:
type: str
required: true
garage_traefik_network:
type: str
default: proxy
garage_internal_network:
type: str
default: internal
garage_use_ssl:
type: bool
default: true
garage_bootstrap_enabled:
type: bool
default: false
description: When true the bootstrap task ensures the node is in the layout.
garage_bootstrap_zone:
type: str
default: dc1
description: Zone label assigned during layout bootstrap.
garage_bootstrap_capacity:
type: str
default: 1G
description: Capacity string passed to C(garage layout assign -c).
garage_s3_keys:
type: list
elements: dict
default: []
description:
- Declarative key + bucket + permission provisioning. The role
creates missing keys, missing buckets, and runs C(bucket allow)
only when the current RWO flags for a given key don't match.
options:
name:
type: str
required: true
buckets:
type: list
elements: dict
description: Buckets this key gets access to.
options:
name:
type: str
required: true
permissions:
type: list
elements: str
choices: [read, write, owner]
required: true

123
roles/nextcloud/README.md Normal file
View 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
View 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.

108
roles/traefik/README.md
View file

@ -1,38 +1,98 @@
Role Name
=========
# Traefik
A brief description of the role goes here.
Ansible role to deploy Traefik v3 as a reverse proxy via Docker Compose,
either as a public-facing DMZ proxy (file provider) or as a backend
application proxy (docker provider).
Requirements
------------
## Requirements
Any pre-requisites that may not be covered by Ansible itself or the role should be mentioned here. For instance, if the role uses the EC2 module, it may be a good idea to mention in this section that the boto package is required.
- Docker and Docker Compose installed on the target host
- Ansible collection: `community.docker`
- For ACME DNS-01: an RFC2136-capable nameserver with a delegated zone
for `_acme-challenge` records and a TSIG key
Role Variables
--------------
## Role variables
A description of the settable variables for this role should go here, including any variables that are in defaults/main.yml, vars/main.yml, and any variables that can/should be set via parameters to the role. Any variables that are read from other roles and/or the global scope (ie. hostvars, group vars, etc.) should be mentioned here as well.
Full list with types and defaults: `meta/argument_specs.yml`. The most
common overrides:
Dependencies
------------
### Deployment mode
A list of other roles hosted on Galaxy should go here, plus any details in regards to parameters that may need to be set for other roles, or variables that are used from other roles.
- `traefik_mode`: `dmz` (file provider, routes to external backends) or
`backend` (docker provider, discovers local containers). Default `backend`.
- `traefik_backend_servers_to_proxy`: in `dmz` mode, restrict which
inventory hosts the DMZ aggregates services from. Empty = all members
of `backend_servers`.
Example Playbook
----------------
### Networking
Including an example of how to use your role (for instance, with variables passed in as parameters) is always nice for users too:
- `traefik_network`: docker network connecting traefik to its containers
(default `proxy`).
- `traefik_extra_hosts`: list of `host:ip` entries injected as the
container's `extra_hosts`. Use when a downstream middleware
(e.g. ForwardAuth to authentik on a sibling LAN) must resolve a public
FQDN to an internal IP because the DMZ does not hairpin the public
address back inside.
- hosts: servers
roles:
- { role: username.rolename, x: 42 }
### Certificates
License
-------
- `traefik_cert_mode`: `acme` (Let's Encrypt via DNS-01) or `selfsigned`
(local wildcard). Default `selfsigned`.
- `traefik_acme_dns_zone`, `traefik_acme_dns_nameserver`,
`traefik_acme_tsig_key`, `traefik_acme_tsig_secret`: RFC2136 / TSIG
configuration for the ACME DNS-01 challenge.
- `traefik_acme_tcp_only`: force lego's DNS lookups onto TCP/53 when the
container cannot reach the nameserver over UDP.
- `traefik_acme_disable_ans_checks`: skip the authoritative-NS
propagation check when the SOA-listed NS resolves to an unreachable IP.
BSD
### Dashboard
Author Information
------------------
- `traefik_enable_dashboard`: expose the traefik dashboard.
- `traefik_dashboard_domain`: when set, publish the dashboard on this
Host rule instead of the insecure port.
An optional section for the role authors to include contact information, or a website (HTML is not allowed).
## Dependencies
- Traefik network (`traefik_network`, default `proxy`) must be created
by the `base` role or by hand before this role runs.
- In `dmz` mode, the proxied backend services advertise themselves via
the `traefik_services` host_var on each backend host.
## Example playbook
Backend mode (one app server per host, docker provider):
```yaml
- hosts: app_servers
roles:
- role: digitalboard.core.traefik
vars:
traefik_mode: backend
traefik_cert_mode: acme
traefik_ssl_email: ops@example.com
traefik_acme_dns_zone: "_acme.example.com."
traefik_acme_dns_nameserver: "10.0.0.53:53"
traefik_acme_tsig_key: "acme-key"
traefik_acme_tsig_secret: "{{ vault_traefik_tsig_secret }}"
```
DMZ mode (aggregates services from `backend_servers`):
```yaml
- hosts: dmz_servers
roles:
- role: digitalboard.core.traefik
vars:
traefik_mode: dmz
traefik_cert_mode: acme
traefik_backend_servers_to_proxy:
- app01
- app02
traefik_extra_hosts:
- "auth.example.com:172.16.19.101"
```
## License
MIT-0

215
roles/traefik/meta/argument_specs.yml Normal file
View file

@ -0,0 +1,215 @@
---
argument_specs:
main:
short_description: Deploy Traefik v3 as DMZ or backend reverse proxy via Docker Compose.
description:
- Renders a Docker Compose stack for Traefik with either the file provider
(DMZ mode, routes to external backends) or the docker provider (backend
mode, discovers local containers via labels).
- Supports ACME DNS-01 issuance (RFC2136 / TSIG) or a self-signed cert
bundle for local/Vagrant setups.
options:
docker_compose_base_dir:
type: path
default: /etc/docker/compose
description: Base directory under which the per-service compose dir is created.
docker_volume_base_dir:
type: path
default: /srv/data
description: Base directory under which the per-service volume dir is created.
service_name:
type: str
default: traefik
description: Compose project / service name; also used to build the per-service paths.
docker_compose_dir:
type: path
description: Compose project directory; defaults to C({{ docker_compose_base_dir }}/{{ service_name }}).
docker_volume_dir:
type: path
description: Per-service volume directory; defaults to C({{ docker_volume_base_dir }}/{{ service_name }}).
traefik_extra_hosts:
type: list
elements: str
default: []
description:
- Entries injected as C(extra_hosts) on the traefik container.
- Each entry has the Docker syntax C("host:ip").
- Useful when a downstream middleware (e.g. ForwardAuth to authentik
on a sibling LAN) must resolve a public FQDN to an internal IP
because the DMZ does not hairpin the public address.
traefik_mode:
type: str
choices: [dmz, backend]
default: backend
description:
- C(dmz) configures the file provider so the proxy forwards to
backend hosts (typically aggregated from the C(backend_servers) group).
- C(backend) configures the docker provider for local container discovery.
traefik_use_ssl:
type: bool
default: true
description: Toggle TLS on the websecure entrypoint.
traefik_ssl_email:
type: str
default: admin@example.com
description: Contact e-mail used by the ACME resolver.
traefik_ssl_cert_resolver:
type: str
default: dns
description: Certificate resolver name referenced in router labels.
traefik_cert_mode:
type: str
choices: [acme, selfsigned]
default: selfsigned
description: C(acme) for Let's Encrypt via DNS-01, C(selfsigned) for a locally generated bundle.
traefik_acme_dns_zone:
type: str
default: ''
description: Delegated zone used for the TSIG-signed updates (e.g. C(_acme.example.com.)).
traefik_acme_dns_nameserver:
type: str
default: ''
description: Nameserver lego talks to for the DNS challenge (C(host:port)).
traefik_acme_tsig_algorithm:
type: str
default: hmac-sha256
description: TSIG algorithm.
traefik_acme_tsig_key:
type: str
default: ''
description: TSIG key name.
traefik_acme_tsig_secret:
type: str
default: ''
description: TSIG secret (base64).
traefik_acme_propagation_timeout:
type: str
default: '120'
description: lego DNS propagation timeout in seconds.
traefik_acme_polling_interval:
type: str
default: '2'
description: lego DNS propagation polling interval in seconds.
traefik_acme_ttl:
type: str
default: '60'
description: TTL applied to the C(_acme-challenge) TXT records.
traefik_acme_tcp_only:
type: bool
default: false
description:
- Sets C(LEGO_EXPERIMENTAL_DNS_TCP_ONLY=true) on the container so SOA
resolution and propagation checks use TCP/53. Use when UDP/53 is
blocked or unreliable on the container egress path.
traefik_acme_disable_ans_checks:
type: bool
default: false
description:
- Disable lego's propagation check against the zone's authoritative
nameservers (sets C(LEGO_DISABLE_CNAME_SUPPORT=) plus the
authoritative-NS-check skip). Use when the SOA-listed NS hostname
resolves to an address the proxy host cannot reach.
traefik_selfsigned_cert_dir:
type: path
description: Output directory for the self-signed bundle.
traefik_selfsigned_cert_days:
type: int
default: 365
description: Validity in days for the self-signed bundle.
traefik_selfsigned_common_name:
type: str
default: '*.local.test'
description: CN/SAN of the self-signed wildcard cert.
traefik_enable_dashboard:
type: bool
default: false
description: Expose the traefik dashboard.
traefik_dashboard_domain:
type: str
default: ''
description:
- When non-empty, the dashboard is published on this Host rule instead
of the insecure port 8080.
traefik_enable_access_logs:
type: bool
default: true
traefik_access_log_format:
type: str
choices: [common, json]
default: common
traefik_log_level:
type: str
choices: [DEBUG, INFO, WARN, ERROR, FATAL, PANIC]
default: INFO
traefik_network:
type: str
default: proxy
description: Docker network connecting traefik to its routable containers.
traefik_dmz_exposed_services:
type: list
elements: dict
default: []
description:
- In C(dmz) mode, services collected from backend host_vars are
published via the file provider. Each entry needs C(name),
C(domain), C(port); C(protocol) and C(backend_host) are optional.
options:
name:
type: str
required: true
domain:
type: str
required: true
port:
type: int
required: true
protocol:
type: str
choices: [http, https]
default: http
backend_host:
type: str
description: Override the auto-selected backend host.
traefik_services:
type: list
elements: dict
default: []
description:
- Services defined directly on the DMZ proxy (not auto-discovered
from a backend host). Each entry must set C(backend_host).
options:
name:
type: str
required: true
domain:
type: str
required: true
backend_host:
type: str
required: true
port:
type: int
required: true
protocol:
type: str
choices: [http, https]
default: http
traefik_backend_servers_to_proxy:
type: list
elements: str
default: []
description:
- In C(dmz) mode, explicit list of backend hosts the DMZ proxy
should aggregate exposed services from. Empty means all members
of the C(backend_servers) inventory group.