<!-- markdownlint-disable MD013 -->
# Getting Started

[← Documentation index](README.md)

From zero to your first deploy. This page walks through prerequisites,
setup, and the first Ansible run. Deeper details are linked along the way.

## Prerequisites

### Access (to be set up out-of-band)

- **WKS account with OIDC access to OpenBao.** The login runs via
  `bao login -method=oidc -path=Digitalboard`. Without an authorized
  account, authentication fails — and without a token there is no
  secret lookup, hence no deploy.
- **Bao policy / mount read.** The account needs **Read** on the
  mount of the target inventory (e.g. `demo-gymburgdorf/data/*`). Which
  paths an inventory reads is documented in the `host_vars/.../<service>.yml`
  (see [secrets.md § Secret pattern](secrets.md#secret-pattern-bao-lookup)).
- **SSH key on the target hosts.** The hosts are provisioned as `root`
  (`ansible_user: root`, no bastion/jump host). Your own public key
  must be placed out-of-band as `root` on the hosts.
- **Network access (VPN).** `bao.digitalboard.ch` and the host networks
  (`172.16.9.0/24` DMZ, `172.16.19.0/24` backend) are not publicly
  reachable — access requires VPN/network access into the Digitalboard network.

### Tools on the control node

- `ansible` (Core ≥ 2.15) — `ansible --version` to check
- `bao` CLI ([OpenBao](https://openbao.org/)) — e.g.
  `sudo pacman -S openbao python-hvac` (Arch) or via Homebrew
- `python-hvac` (for `community.hashi_vault` lookups)
- On macOS: `OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES` (set in the
  [Makefile](../Makefile)) — without this env var, Ansible forks crash
  on the first Bao lookup, because the Objective-C runtime is not
  fork-safe.

## 1. Clone the repo and install collections

```bash
git clone https://git.digitalboard.ch/Digitalboard/reference-ansible
cd reference-ansible
make install         # community.hashi_vault + digitalboard.core into ./collections/
```

There is **no** `roles/` directory in the repo — all roles come from
the `digitalboard.core` collection. See
[inventories.md § Repo layout](inventories.md#repo-layout-and-role-origin).

## 2. Log in to OpenBao

The login must happen in the **same shell** in which
`ansible-playbook` then runs — details and the `make bao` caveat in
[secrets.md § OpenBao login](secrets.md#openbao-login):

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

## 3. Check connectivity (smoke test)

```bash
make ping_demo       # ping module against all three demo inventories
```

If a host does not respond, it is usually due to the SSH key
(prerequisite above) or missing network access (VPN).

## 4. Run Ansible (deploy)

```bash
make deploy_site_demo_gymburgdorf       # single demo site
```

At its core, `make` only calls `ansible-playbook` — the equivalent
direct invocation:

```bash
ansible-playbook playbooks/site.yml \
  -i inventories/demo-gymburgdorf/hosts.yml --diff
```

All variants (direct invocation, `--limit`, `--tags`, check mode) and
the make targets are documented in [ansible.md § Running Ansible](ansible.md#running-ansible).

## Next steps

- **What happens during a deploy?** → [ansible.md § Playbook](ansible.md#playbook-siteyml)
- **Create a new tenant** → [inventories.md § Walkthrough](inventories.md#walkthrough-creating-a-new-demo-tenant)
- **Store secrets in Bao** → [secrets.md](secrets.md)