reference-ansible/README.md

<!-- markdownlint-disable MD013 -->
# 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`](https://git.digitalboard.ch/Digitalboard/digitalboard.core)
(via [requirements.yml](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](https://openbao.org/). The
only playbook is [playbooks/site.yml](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](docs/inventories.md#walkthrough-creating-a-new-demo-tenant).

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

## Documentation

In-depth documentation lives in the [`docs/`](docs/) folder — start with
the index [docs/README.md](docs/README.md):

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

## Repository structure

```text
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](docs/inventories.md#repo-layout-and-role-origin).

## 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](docs/getting_started.md)**.

```bash
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](docs/secrets.md#openbao-login).
Prerequisites, all make targets, and the deploy flow:
[docs/operations.md](docs/operations.md). Invoking Ansible directly
(`--limit`, `--check`): [docs/ansible.md § Running Ansible](docs/ansible.md#running-ansible).

## Available playbooks

The only playbook is [playbooks/site.yml](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](docs/ansible.md)**.

## Inventories

| Inventory | Purpose |
| --- | --- |
| [`inventories/demo-gymburgdorf/`](inventories/demo-gymburgdorf/) | Demo tenant — recommended as a template for new tenants, see [docs/inventories.md](docs/inventories.md#walkthrough-creating-a-new-demo-tenant) |
| [`inventories/demo-mbazürich/`](inventories/demo-mbazürich/) | Demo tenant |
| [`inventories/demo-phbern/`](inventories/demo-phbern/) | Demo tenant |
| [`inventories/vagrant/`](inventories/vagrant/) | Local test VMs; **incompatible group topology** compared to the demo inventories |