docs(reference-ansible): add docs/ tree and document repo, playbooks, Makefile

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.

.gitignore

@@ -18,3 +18,5 @@
 /collections/ansible_collections/
 .vagrant/
 bao
+
+playbooks/secrets/backend/homarr_secret_encryption_key

docs/ansible.md

@@ -18,22 +18,33 @@ consists of a sequence of plays, each applying one role from
 | # | Play / role | `hosts:` | Target in `demo-gymburgdorf`? |
 | --- | --- | --- | --- |
 | 1 | `digitalboard.core.base` | `all_servers` | ✅ all 4 hosts |
-| 2 | `digitalboard.core.traefik` | `traefik_servers` | ✅ all 4 (dmz on `reverseproxy`, otherwise backend) |
-| 3 | `digitalboard.core.httpbin` | `httpbin_servers` | — no-op |
-| 4 | `digitalboard.core.389ds` | `ds389_servers` | — no-op |
-| 5 | `digitalboard.core.keycloak` | `keycloak_servers` | — no-op |
-| 6 | `digitalboard.core.garage` | `garage_servers` | ✅ `storage` |
-| 7 | `digitalboard.core.collabora` | `collabora_servers` | ✅ `application` |
-| 8 | `digitalboard.core.authentik` | `authentik_servers` | ✅ `application` |
-| 9 | `digitalboard.core.authentik_outpost_ldap` | `authentik_outpost_ldap_servers` | ✅ `application` |
-| 10 | `digitalboard.core.nextcloud` | `nextcloud_servers` | ✅ `application` |
-| 11 | `digitalboard.core.drawio` | `drawio_servers` | ✅ `application` |
-| 12 | `digitalboard.core.send` | `send_servers` | ✅ `application` |
-| 13 | `digitalboard.core.opnform` | `opnform_servers` | ✅ `application` |
-| 14 | `digitalboard.core.homarr` | `homarr_servers` | ✅ `application` |
-| 15 | `digitalboard.core.bookstack` | `bookstack_servers` | ✅ `application` |
-| 16 | `digitalboard.core.opencloud` | `opencloud_servers` | — no-op (no group) |
+| 2 | `digitalboard.core.traefik` | `traefik_servers_backend` | — no-op (vagrant-only group) |
+| 3 | `digitalboard.core.traefik` | `traefik_servers_dmz` | — no-op (vagrant-only group) |
+| 4 | `digitalboard.core.traefik` | `traefik_servers:!traefik_servers_dmz:!traefik_servers_backend` | ✅ all 4 (dmz on `reverseproxy`, otherwise backend) |
+| 5 | `digitalboard.core.httpbin` | `httpbin_servers` | — no-op |
+| 6 | `digitalboard.core.389ds` | `ds389_servers` | — no-op |
+| 7 | `digitalboard.core.keycloak` | `keycloak_servers` | — no-op |
+| 8 | `digitalboard.core.garage` | `garage_servers` | ✅ `storage` |
+| 9 | `digitalboard.core.collabora` | `collabora_servers` | ✅ `application` |
+| 10 | `digitalboard.core.authentik` | `authentik_servers` | ✅ `application` |
+| 11 | `digitalboard.core.authentik_outpost_ldap` | `authentik_outpost_ldap_servers` | ✅ `application` |
+| 12 | `digitalboard.core.nextcloud` | `nextcloud_servers` | ✅ `application` |
+| 13 | `digitalboard.core.drawio` | `drawio_servers` | ✅ `application` |
+| 14 | `digitalboard.core.send` | `send_servers` | ✅ `application` |
+| 15 | `digitalboard.core.opnform` | `opnform_servers` | ✅ `application` |
+| 16 | `digitalboard.core.homarr` | `homarr_servers` | ✅ `application` |
+| 17 | `digitalboard.core.bookstack` | `bookstack_servers` | ✅ `application` |
+| 18 | `digitalboard.core.opencloud` | `opencloud_servers` | — no-op (no group) |
 
+> **Three traefik plays, two topologies.** `vagrant` splits the reverse
+> proxy into `traefik_servers_dmz` + `traefik_servers_backend` (plays 2
+> and 3). The demo inventories (e.g. `demo-gymburgdorf`) instead group
+> all hosts under `traefik_servers` and select dmz/backend per host via
+> `traefik_mode`; play 4's `:!…` intersection targets exactly those
+> hosts and stays a no-op for the vagrant split. Each topology thus
+> triggers only the traefik play(s) that fit it — no host runs traefik
+> twice.
+>
 > Which plays take effect for a tenant is controlled **solely through
 > group membership** in `hosts.yml`. A service becomes active as soon as
 > its `<service>_servers` group contains a host and a matching

inventories/vagrant/host_vars/backend/homarr.yml

@@ -0,0 +1,11 @@
+homarr_domain: "home.local.test"
+
+homarr_secret_dir: "{{ playbook_dir }}/secrets/{{ inventory_hostname }}"
+homarr_secret_file: "homarr_secret_encryption_key"
+homarr_secret_length: 64
+
+homarr_secret_encryption_key: >-
+  {{ lookup('ansible.builtin.password',
+            homarr_secret_dir ~ '/' ~ homarr_secret_file,
+            length=homarr_secret_length,
+            chars='hexdigits') }}

inventories/vagrant/host_vars/backend/nextcloud.yml

@@ -35,6 +35,7 @@ nextcloud_extra_networks:
 
 nextcloud_extra_hosts:
   - "storage.local.test:192.168.56.11"
+  - "office.local.test:192.168.56.11"
   - "keycloak.local.test:192.168.56.11"
   - "authentik.local.test:192.168.56.11"
   # - "389ds:192.168.56.11"  # only needed when using 389ds LDAP directly

inventories/vagrant/host_vars/backend/opnform.yml

@@ -0,0 +1,13 @@
+opnform_domain: "forms.local.test"
+
+opnform_secret_dir: "{{ playbook_dir }}/secrets/{{ inventory_hostname }}"
+opnform_secret_file: "opnform_secret_encryption_key"
+opnform_secret_length: 64
+opnform_admin_email: "admin@digitalboard.ch"
+opnform_admin_password: "ChangeMe123!"
+
+opnform_secret_encryption_key: >-
+  {{ lookup('ansible.builtin.password',
+            opnform_secret_dir ~ '/' ~ opnform_secret_file,
+            length=opnform_secret_length,
+            chars='hexdigits') }}

inventories/vagrant/host_vars/backend/traefik.yml

@@ -16,7 +16,7 @@ traefik_dmz_exposed_services:
     domain: nextcloud.local.test
     port: 443
     protocol: https
-  - name: collabora
+  - name: nextcloud-collabora
     domain: office.local.test
     port: 443
     protocol: https
@@ -24,12 +24,12 @@ traefik_dmz_exposed_services:
     domain: authentik.local.test
     port: 443
     protocol: https
-  - name: opencloud
-    domain: opencloud.local.test
+  - name: homarr
+    domain: home.local.test
     port: 443
     protocol: https
-  - name: drawio
-    domain: drawio.local.test
+  - name: opnform
+    domain: forms.local.test
     port: 443
     protocol: https
   # Example: Add more services as you deploy them

inventories/vagrant/hosts.yml

@@ -45,11 +45,11 @@ all:
         backend:
         backend2:
 
-    keycloak_servers:
+    ds389_servers:
       hosts:
         backend:
 
-    ds389_servers:
+    keycloak_servers:
       hosts:
         backend:
 
@@ -69,6 +69,10 @@ all:
       hosts:
         backend:
 
+    homarr_servers:
+      hosts:
+        backend:
+
     collabora_servers:
       hosts:
         backend:
@@ -81,6 +85,6 @@ all:
       hosts:
         backend:
 
-    openforms_servers:
+    opnform_servers:
       hosts:
         backend:

playbooks/site.yml

@@ -5,8 +5,25 @@
   roles:
     - digitalboard.core.base
 
+- name: Configure reverse proxy on application servers
+  hosts: traefik_servers_backend
+  become: yes
+  roles:
+    - digitalboard.core.traefik
+
+- name: Configure reverse proxy on DMZ servers
+  hosts: traefik_servers_dmz
+  become: yes
+  roles:
+    - digitalboard.core.traefik
+
+# Inventories without the _dmz/_backend split (e.g. demo-gymburgdorf,
+# where traefik_servers groups all_servers and dmz/backend is selected
+# per host via traefik_mode). The :!… intersection keeps this a no-op
+# for the vagrant topology, where every traefik_servers host is already
+# covered by the two plays above.
 - name: Configure reverse proxies
-  hosts: traefik_servers
+  hosts: traefik_servers:!traefik_servers_dmz:!traefik_servers_backend
   become: yes
   roles:
     - digitalboard.core.traefik