<!-- markdownlint-disable MD013 MD060 MD051 -->
# Deploy flow and Traefik modes

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

## 6. Deploy flow

Sequence taken from [playbooks/site.yml](https://git.digitalboard.ch/Digitalboard/reference-ansible/src/branch/main/playbooks/site.yml):

```mermaid
sequenceDiagram
    participant U as User
    participant A as ansible-playbook
    participant V as OpenBao
    participant H as Hosts

    U->>U: bao login + export VAULT_TOKEN
    U->>A: make deploy_site_demo_gymburgdorf
    A->>A: load vars: role defaults → group_vars/all → group_vars/&lt;groups&gt; → host_vars/&lt;host&gt;
    A->>V: community.hashi_vault lookups<br/>(acme-tsig, service secrets)
    V-->>A: secret values
    A->>H: Play 1 — base (all hosts)
    A->>H: Play 2 — traefik (all hosts: dmz on reverseproxy, backend elsewhere)
    A->>H: Play 3 — httpbin
    A->>H: Play 4 — 389ds
    A->>H: Play 5 — keycloak
    A->>H: Play 6 — garage (storage)
    A->>H: Play 7 — collabora (application)
    A->>H: Play 8 — authentik (application)
    A->>H: Play 9 — authentik_outpost_ldap (application)
    A->>H: Play 10 — nextcloud (application)
    A->>H: Play 11 — drawio (application)
    A->>H: Play 12 — send
    A->>H: Play 13 — opnform
    A->>H: Play 14 — homarr
    A->>H: Play 15 — bookstack
    A->>H: Play 16 — opencloud
```

Plays without matching group members (`httpbin_servers`,
`ds389_servers`, `keycloak_servers`, `send_servers`,
`opnform_servers`, `homarr_servers`, `bookstack_servers`,
`opencloud_servers` in this inventory) run as no-ops.

> **Role-name spelling traps:** the LDAP role is `389ds` (not
> `ds389`); the forms role is `opnform` (not `openforms`/`openform`).
> Inventory groups must match the names used in
> [playbooks/site.yml](https://git.digitalboard.ch/Digitalboard/reference-ansible/src/branch/main/playbooks/site.yml) exactly —
> `ds389_servers`, `opnform_servers`.

`--diff` is enabled in the target → per-task changes are visible.

## 7. Traefik modes (DMZ vs Backend)

**`traefik_mode: dmz`** — public-facing reverse proxy on `reverseproxy`:

- **File provider** with `services.yml` for static routing.
- No Docker socket mounted, no local containers.
- Routes to `backend_host` addresses on other machines.
- Backends are declared via `traefik_dmz_exposed_services` (a list in
  `host_vars/reverseproxy/`). Selective backend selection is also
  possible via `traefik_backend_servers_to_proxy`.

**`traefik_mode: backend`** — application/storage:

- Mounts `/var/run/docker.sock`.
- **Docker provider**: auto-discovery via container labels
  (`traefik.enable=true`).
- Services are exposed locally; the DMZ Traefik routes external
  traffic to them in plaintext HTTP (see
  [security.md](security.md)).

**Both modes** support ACME via RFC2136 DNS challenge or self-signed
(`traefik_cert_mode: acme | selfsigned`).