2ba0c07cd3
Addresses the WKS PoC review (Notion 2026-05-26). All docs in English. - README: purpose, docs table of contents, annotated repo tree - docs/getting_started.md: prerequisites (WKS account, OIDC, SSH, VPN) + first deploy - docs/ansible.md: playbook table, "Running Ansible", service parameters, cheatsheet - docs/secrets.md: canonical Bao login (moved out of README) + demo defaults - docs/operations.md: full Makefile reference - docs/inventories.md: repo layout, topology, standard folder structure, walkthrough - docs/testing.md: static checks, inventory resolution, smoke test / dry run - remove ARCHITECTURE.md (architecture docs live externally) Also includes the gymburgdorf inventory build-out (bookstack, homarr, opnform, send) and scripts/bao-seed.sh. site.yml keeps a third traefik play (traefik_servers minus the vagrant _dmz/_backend split) so the demo inventories still configure their reverse proxy after the rebase onto main.
93 lines
3.4 KiB
Markdown
93 lines
3.4 KiB
Markdown
<!-- 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)
|