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

docs(bookstack): add meta/argument_specs.yml

Browse source 
47 typed options covering the full defaults file plus the OIDC and
backup-timer subsystems. The three secrets the role asserts on
(db_root_password, db_password, admin_password) are marked
required: true so ansible refuses the play with a clear error before
the validate task even runs.

Loads cleanly through ansible-core's ArgumentSpecValidator with 100%
defaults/spec coverage. Matches the spec convention used by traefik,
authentik, drawio, garage, nextcloud, opnform, coturn, talk and send.
This commit is contained in:
Simon Bärlocher 2026-05-26 15:13:30 +02:00
parent 4fe9d6b177
commit 9cbfab7080
No known key found for this signature in database
GPG key ID: 63DE20495932047A
1 changed files with 194 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

194
roles/bookstack/meta/argument_specs.yml Normal file
View file

@ -0,0 +1,194 @@
---
argument_specs:
main:
short_description: Deploy BookStack (LSIO image + MariaDB) via Docker Compose.
description:
- Renders a Compose stack for the linuxserver.io BookStack image
with a sibling MariaDB container behind Traefik, then bootstraps
the initial admin user via C(php artisan bookstack:create-admin)
and optionally enables OIDC SSO (Entra ID by default).
- "Persists the Laravel C(APP_KEY) on the host so the same key is
re-used across deploys (a fresh key would orphan all encrypted
database values: 2FA secrets, API tokens, OIDC client_secret)."
- Ships an optional systemd timer that backs up the database dump,
uploads tarball and APP_KEY daily with configurable retention.
options:
docker_compose_base_dir:
type: path
default: /etc/docker/compose
docker_volume_base_dir:
type: path
default: /srv/data
bookstack_service_name:
type: str
default: bookstack
bookstack_docker_compose_dir:
type: path
bookstack_docker_volume_dir:
type: path
bookstack_appdata_dir:
type: path
bookstack_db_data_dir:
type: path
bookstack_backup_dir:
type: path
bookstack_domain:
type: str
default: wiki.local.test
description: Hostname used in the Traefik Host rule.
bookstack_base_url:
type: str
description: Defaults to C("https://{{ bookstack_domain }}").
bookstack_image:
type: str
default: "lscr.io/linuxserver/bookstack:version-v26.03.3"
bookstack_db_image:
type: str
default: "lscr.io/linuxserver/mariadb:11.4.9"
bookstack_traefik_network:
type: str
default: proxy
bookstack_traefik_certresolver:
type: str
default: le
bookstack_tz:
type: str
default: Europe/Zurich
bookstack_puid:
type: str
default: "1000"
bookstack_pgid:
type: str
default: "1000"
bookstack_db_name:
type: str
default: bookstack
bookstack_db_user:
type: str
default: bookstack
bookstack_db_root_password:
type: str
required: true
description: MariaDB C(root) password. Override per-inventory.
bookstack_db_password:
type: str
required: true
description: MariaDB C(bookstack_db_user) password. Override per-inventory.
bookstack_admin_password:
type: str
required: true
description:
- Password for the local admin user that the role creates via
C(bookstack:create-admin). Lives alongside any OIDC users.
bookstack_app_key:
type: str
default: ''
description:
- When empty the role generates a persistent C(APP_KEY) on first
run and stores it under C({{ bookstack_docker_volume_dir }}/.app_key).
Override only when restoring an existing instance — a mismatching
key orphans all encrypted database values.
bookstack_admin_name:
type: str
default: Admin
bookstack_admin_email:
type: str
default: admin@local.test
bookstack_artisan_path:
type: path
default: /app/www/artisan
description:
- Path to BookStack's C(artisan) script inside the container. The
LSIO image's C(WORKDIR) is not the app directory, so this must
be absolute.
bookstack_mail_driver:
type: str
choices: [smtp, log, sendmail, mailgun, ses, postmark]
default: smtp
bookstack_mail_host:
type: str
default: smtp.local.test
bookstack_mail_port:
type: int
default: 587
bookstack_mail_encryption:
type: str
choices: [tls, ssl, '']
default: tls
bookstack_mail_from:
type: str
default: bookstack@local.test
bookstack_mail_from_name:
type: str
default: BookStack
bookstack_mail_username:
type: str
default: ''
bookstack_mail_password:
type: str
default: ''
bookstack_oidc_enabled:
type: bool
default: false
bookstack_oidc_name:
type: str
default: SSO
description: Display name of the SSO button on the login page.
bookstack_entra_tenant_id:
type: str
default: ''
description: Entra tenant UUID. Required when C(bookstack_oidc_enabled=true).
bookstack_oidc_issuer:
type: str
description:
- OIDC issuer URL. Defaults to the Entra v2 issuer template
built from C(bookstack_entra_tenant_id). Override for
Keycloak or any other provider.
bookstack_oidc_client_id:
type: str
default: ''
description: Required when C(bookstack_oidc_enabled=true).
bookstack_oidc_client_secret:
type: str
default: ''
description: Required when C(bookstack_oidc_enabled=true).
bookstack_oidc_auto_initiate:
type: bool
default: false
description:
- When true users are redirected straight to the IdP and the
local login is reachable only via C(?email_login=1).
bookstack_oidc_user_to_groups:
type: bool
default: false
description:
- When true BookStack syncs roles from the IdP groups claim
on every login. Requires BookStack roles whose
C(External Auth ID) matches the IdP group's Object ID.
bookstack_oidc_groups_claim:
type: str
default: groups
bookstack_oidc_additional_scopes:
type: str
default: openid profile email
bookstack_backup_enabled:
type: bool
default: true
bookstack_backup_retention_days:
type: int
default: 14
bookstack_backup_schedule:
type: str
default: "*-*-* 03:00:00"
description: systemd C(OnCalendar) expression for the backup timer.