<!-- markdownlint-disable MD013 MD060 MD051 -->
# Setup and repo layout

← Back to [Architecture index](README.md)

## 1. Repo layout and role provenance

```text
reference-ansible/
├── Makefile                     # Deploy targets, OIDC login, OBJC fork workaround
├── ansible.cfg                  # collections_path, remote_user=root, hashi_vault auth_method=token
├── requirements.yml             # community.hashi_vault + digitalboard.core (Git)
├── playbooks/site.yml           # Play sequence (14 plays, see deploy.md)
├── collections/                 # ← installed by `make install`, gitignored
│   └── ansible_collections/
│       └── digitalboard/core/
│           └── roles/           # 🔑 Roles live HERE, NOT in the repo root
└── inventories/
    ├── demo-gymburgdorf/        # Inventory used throughout this document
    ├── demo-mbazürich/
    ├── demo-phbern/
    └── vagrant/                 # Local test inventory with its own topology
```

> **Important:** There is **no** `roles/` directory at the repo root.
> All roles come from the `digitalboard.core` collection (see
> [requirements.yml](https://git.digitalboard.ch/Digitalboard/reference-ansible/src/branch/main/requirements.yml)), installed via `make install`
> into `./collections/`. Plays reference them by FQCN
> `digitalboard.core.<role>`.

## 2. Setup and prerequisites

**Tools on the control node:**

- `ansible` (Core ≥ 2.15)
- `bao` CLI (OpenBao) — e.g. `sudo pacman -S openbao python-hvac` (Arch) or Homebrew
- `python-hvac` (for `community.hashi_vault` lookups)
- On macOS: `OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES` (set in the
  [Makefile](https://git.digitalboard.ch/Digitalboard/reference-ansible/src/branch/main/Makefile); without it Ansible forks crash on Bao lookups)

**Initial setup:**

```bash
git clone <repo>
cd reference-ansible
make install         # Galaxy + digitalboard.core into ./collections/
```

**Before every deploy:** Bao login in the **same shell** that will then
run `ansible-playbook`:

```bash
export BAO_ADDR=https://bao.digitalboard.ch
bao login -method=oidc -path=Digitalboard
export VAULT_TOKEN=$(bao print token)
```

> ⚠️ `make bao` on its own is **not enough**: every `make` target spawns
> a new shell, and the `VAULT_TOKEN` exported in there only lives for
> the duration of `make bao` itself. Either run the three commands
> above manually, or invoke `make bao deploy_site_demo_gymburgdorf` as
> **one** call — otherwise the deploy has no token.

**Smoke test:**

```bash
make ping_demo       # pings all three demo inventories
```