ansible-content/README.md

# ansible-content

Ansible-Rollen, die der Tuxflotte Provisioning Agent per `ansible-pull` gegen installierte Geräte anwendet.

Rollennamen entsprechen 1:1 der Spalte `ansible_role` in der `blueprints`-Tabelle des Provisioning-Servers (siehe `provisioning-server/migrations/0005_seed_workspace_backend_blueprint_data.sql`).

**Namenskonvention:** Der Fedora-Installer wurde zurückgestellt (Installationsprobleme, Pilot-Schulen laufen auf Mint) — aktueller Fokus liegt auf dem Management von Mint-Geräten, später weiteren Distros, ggf. auch wieder Fedora. Rollen ohne Distro-Suffix (z.B. `brave`, `onlyoffice`, `guest-session`) sind bewusst distributionsunabhängig gebaut und laufen auf jedem unterstützten Backend. Ein `-mint`-Suffix kennzeichnet eine Rolle, die tatsächlich Mint/Debian-spezifische Logik braucht (aktuell keine vorhanden). Kein Backend-Name sollte für eine Rolle stehen, die eigentlich generisch funktioniert.

`site.yml` bindet jede Rolle unter einem zu ihrem Namen passenden Tag ein. Der Agent ruft sie über:

```
ansible-pull -U <repo-url> --tags <rolle1>,<rolle2>,... -i localhost, site.yml
```

## Aktueller Stand

Alle drei Rollen haben echten Inhalt (Stand 2026-08-04) — die Marker-Dateien unter `/run/tuxflotte/agent/applied/<rolle>.marker` bleiben zusätzlich als schneller E2E-Nachweis bestehen, sind aber nicht mehr der eigentliche Effekt der Rollen:

- **`guest-session`**: echte flüchtige Gastsitzung. Lokaler User `gast`, Login ohne Passwort über die `nopasswdlogin`-Gruppenkonvention, `$HOME` per `pam_namespace`-Polyinstantiation (`/etc/security/namespace.conf`) als tmpfs — wird bei Sitzungsende automatisch verworfen, kein Cleanup-Skript nötig. PAM-Dateilayout unterscheidet sich zwischen RedHat- (`gdm-password`/`postlogin`) und Debian-Familie (`lightdm`/`common-session`) und wird über `ansible_facts['os_family']` erkannt, da derselbe Rollenname für beide Backends (`fedora`, `mint`) verwendet wird.
- **`brave`**: Installation von Brave via Flatpak/Flathub (`community.general.flatpak`) — distributionsunabhängig, läuft für beide Backends. Unterstützt zusätzlich die Auftragskatalog-Option `standardbrowser` (siehe unten).
- **`onlyoffice`**: Installation von OnlyOffice Desktop Editors via Flatpak/Flathub — ebenfalls distributionsunabhängig.

**Neue Abhängigkeit:** die `community.general`-Collection (Module `flatpak`, `flatpak_remote`, `ini_file`). Auf der Zielplattform muss sie installiert sein — auf der bisherigen Test-VM (Linux Mint) bereits vorhanden (`ansible-collection-community-general`), auf frisch installierten Fedora-Geräten ggf. per `ansible-galaxy collection install community.general` oder passendes RPM-Paket sicherstellen.

## present/absent (Auftragskatalog, ADR-0010)

Merkmale, die für die geräteweise Ad-hoc-Zuweisung über den Auftragskatalog freigegeben sind (`merkmale.im_auftragskatalog = true`), können nicht nur zugewiesen, sondern auch wieder abgewählt werden — und das muss real etwas zurückbauen, nicht nur zukünftige Anwendung verhindern.

Dafür reicht der Agent bei jedem `ansible-pull`-Lauf eine Variable `tuxflotte_auftrag_states` durch (Rollenname → `"present"`/`"absent"`, aus der Check-in-Antwort `auftraege`), die `site.yml` pro Rolle als `tuxflotte_state` an die jeweilige Rolle weiterreicht. Rollen, die dort nicht auftauchen (zum Beispiel weil sie nur workspace-komponiert sind, nicht katalogfähig), laufen unverändert additiv über `--tags`, ohne `absent`-Zustand — siehe `tuxflotte_auftrag_states.get(<rolle>, 'present')` in `site.yml`.

Jede Rolle, die katalogfähig werden soll, muss deshalb ihre Tasks auf `tuxflotte_state` verzweigen:

```yaml
- name: <Merkmal anwenden>
  ...
  when: tuxflotte_state == "present"

- name: <Merkmal zurückbauen>
  ...
  when: tuxflotte_state == "absent"
```

`tuxflotte_state` hat in `roles/<name>/defaults/main.yml` den Default `present`, damit die Rolle auch bei direkter Verwendung ohne die `site.yml`-Verdrahtung nicht auf eine undefinierte Variable trifft.

Rollen, die nie katalogfähig werden (rein workspace-komponierte Merkmale), brauchen keinen `absent`-Zweig — das ist bewusst kein Zwang für alle Rollen, nur für die, die tatsächlich im Auftragskatalog landen.

## optionen (Auswahl-Parameter je Zuweisung)

Über die reine present/absent-Zuweisung hinaus kann eine Auftragskatalog-Zuweisung zusätzliche, rollenspezifische Optionen tragen (`device_merkmale.optionen`, JSONB) — z.B. `{"standardbrowser": true}` bei `browser-brave`. Der Server kennt die Bedeutung dieser Optionen nicht, reicht sie nur unverändert durch (Check-in-Antwort `auftraege[].optionen`).

Der Agent baut daraus `tuxflotte_auftrag_optionen` (Rollenname → optionen-Dict) als zweites `--extra-vars`-Feld neben `tuxflotte_auftrag_states`. `site.yml` reicht es pro Rolle als `tuxflotte_optionen` durch (Default `{}`, falls die Rolle nicht in der Map auftaucht). Nur Rollen, die tatsächlich Optionen brauchen, lesen die Variable (aktuell nur `brave`) — für alle anderen ist sie ungenutzt.

## Neue Rolle hinzufügen

0. Namenskonvention beachten: distributionsunabhängig gebaut → kein Suffix (`<name>`), tatsächlich distro-spezifische Logik → Suffix (`<name>-mint`, ggf. später `<name>-fedora`). Im Zweifel distributionsunabhängig bauen (siehe `guest-session`s `os_family`-Erkennung als Vorbild) statt vorschnell zu suffixen.
1. `roles/<name>/tasks/main.yml` anlegen
2. `roles/<name>/defaults/main.yml` mit `tuxflotte_state: present` anlegen
3. Eintrag in `site.yml` mit `tags: <name>` und `vars: tuxflotte_state: "{{ tuxflotte_auftrag_states.get('<name>', 'present') }}"` ergänzen
4. Entsprechenden `ansible_role`-Wert in der `blueprints`-Tabelle referenzieren
5. Nur falls die Rolle katalogfähig werden soll (`im_auftragskatalog = true`): Tasks wie oben auf `tuxflotte_state` verzweigen, sonst reicht der additive Pfad ohne `when`