reference-ansible

Purpose

This repository is the Ansible setup for the Digitalboard demo deployments — reproducible reference tenants on which the full stack (identity, storage, office, forms, dashboards, …) can be set up and demonstrated end-to-end.

It contains no roles of its own: all logic comes from the collection digitalboard.core (via requirements.yml). What lives here is the inventory and configuration layer — one dedicated inventory per tenant under inventories/demo-* that wires up the roles, defines hosts and domains, and pulls secrets from OpenBao. The only playbook is playbooks/site.yml.

The repository thus serves two purposes:

• Demo operation: deploy and keep up to date the existing demo tenants (demo-gymburgdorf, demo-mbazürich, demo-phbern).
• Template: create new tenants following the demo-gymburgdorf pattern — see docs/inventories.md § Walkthrough.

Demo-only. All role defaults (passwords, tokens, RPC secrets) are insecure and intended exclusively for demo setups. For production adaptation, see docs/secrets.md.

Documentation

In-depth documentation lives in the docs/ folder — start with the index docs/README.md:

Document	Content
docs/getting_started.md	Prerequisites (access, tools), first deploy step by step
docs/operations.md	Setup, prerequisites, deploy flow, make targets, smoke test, known gaps
docs/secrets.md	OpenBao login, secret lookup pattern, demo-only defaults, threat boundaries
docs/inventories.md	Repository layout, roles origin, inventory topology, new-tenant walkthrough
docs/ansible.md	Playbooks (site.yml), service parameters, variable cheat sheet
docs/testing.md	Static checks, inventory resolution, smoke test/dry run before the deploy

Repository structure

reference-ansible/
├── Makefile                     # deploy targets, OIDC login, OBJC fork workaround
├── ansible.cfg                  # collections_path, remote_user=root, hashi_vault auth
├── requirements.yml             # community.hashi_vault + digitalboard.core (Git)
├── Vagrantfile                  # local test VMs
├── playbooks/
│   └── site.yml                 # the only playbook — play sequence of all services
├── scripts/
│   └── bao-seed.sh              # seed/merge OpenBao secrets per inventory (idempotent)
├── docs/                        # in-depth documentation (see table above)
├── collections/                 # ← installed by `make install`, gitignored
│   └── ansible_collections/digitalboard/core/roles/   # 🔑 the roles live here
└── inventories/
    ├── demo-gymburgdorf/        # reference tenant — template for new tenants
    │   ├── hosts.yml            # hosts + group topology
    │   ├── group_vars/          # all/ · traefik_servers/ · backend_servers/
    │   └── host_vars/           # reverseproxy/ · application/ · storage/
    ├── demo-mbazürich/          # demo tenant
    ├── demo-phbern/             # demo tenant
    └── vagrant/                 # local test inventory (incompatible topology)

No roles/ in the repository root — all roles come from digitalboard.core and are installed via make install into ./collections/. Plays reference them by FQCN digitalboard.core.<role>. Details: docs/inventories.md.

Quick Start

First time here? Prerequisites (WKS account, OIDC access, SSH key, VPN), tool setup, and the first deploy step by step: docs/getting_started.md.

make install                            # collections into ./collections/

# Log in to OpenBao — in the SAME shell as the deploy.
# Full login flow + make-bao caveat: docs/secrets.md
export BAO_ADDR=https://bao.digitalboard.ch
bao login -method=oidc -path=Digitalboard
export VAULT_TOKEN=$(bao print token)

make ping_demo                          # smoke test against all demo inventories
make deploy_site_demo_gymburgdorf       # single demo site
make deploy_site_demo                   # all three demo sites

Login details and the make bao caveat: docs/secrets.md. Prerequisites, all make targets, and the deploy flow: docs/operations.md. Invoking Ansible directly (--limit, --check): docs/ansible.md § Running Ansible.

Available playbooks

The only playbook is playbooks/site.yml — a sequence of plays, each applying one digitalboard.core role to a host group (base, traefik, garage, authentik, authentik_outpost_ldap, nextcloud, collabora, drawio, send, opnform, homarr, bookstack, …). Which plays take effect in an inventory is governed solely by group membership in hosts.yml. Full play table and all service parameters: docs/ansible.md.

Inventories

Inventory	Purpose
inventories/demo-gymburgdorf/	Demo tenant — recommended as a template for new tenants, see docs/inventories.md
inventories/demo-mbazürich/	Demo tenant
inventories/demo-phbern/	Demo tenant
inventories/vagrant/	Local test VMs; incompatible group topology compared to the demo inventories