Digitalboard/docs
6
1
Fork 0
Code Pull requests 1 Activity Actions
docs/architecture/deploy.md
Simon Bärlocher 345cf4b319
docs: add architecture section and overhaul top-level README 
- Move Simon's architecture documentation into architecture/
  (setup, variables, topology, dns, deploy, security, operations
  plus index and glossary). All cross-repo references point at
  https://git.digitalboard.ch/Digitalboard/{reference-ansible,dns-zones}
  via absolute URLs so the docs remain navigable from any context.
- Rewrite README.md as a documentation hub: introduction, platform
  Mermaid overview, comparison of the three repos
  (docs / digitalboard.core / reference-ansible) and a full table of
  contents covering architecture, contributing, infrastructure,
  keycloak, ms-entra and troubleshooting.

Addresses the open items from the WKS PoC review (2026-05-26):
docs README begrüssungstext + Übersichtsgrafik + Verlinkung der
beiden anderen Repos, sowie das Verschieben der Architektur-Doku.
2026-05-28 14:25:27 +02:00

2.8 KiB
Raw Blame History

Deploy flow and Traefik modes

← Back to Architecture index

6. Deploy flow

Sequence taken from playbooks/site.yml:

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/<groups> → host_vars/<host>
    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 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).

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