added readmes (#1)

Co-authored-by: DerLinkman <derlinkman@gmail.com> Reviewed-on: #1
2026-07-18 19:36:54 +00:00
parent 8d64bf5982
commit cab59c1658
7 changed files with 782 additions and 0 deletions
@@ -0,0 +1,94 @@
+# Rolle `hawser`
+
+Aktualisiert den [Hawser](https://ghcr.io/finsys/hawser) Docker-Compose-Stack
+auf den Ziel-Hosts. Hawser ist ein Docker-Management-Agent, der das Docker-
+Socket nach außen freigibt. Die Rolle deployt die Compose-Datei aus einem
+Template und zieht stets die neuesten Images (`pull: always`).
+
+> Siehe auch das Playbook `playbooks/upgrade-hawser.yml` sowie die
+> [Repo-README](../../README.md).
+
+## Voraussetzungen
+
+- Debian-Ziel-Host mit installierter Docker Engine (Rolle `docker`)
+- Bereits vorhandene Hawser-Installation
+  (`/opt/hawser/docker-compose.yml` muss existieren)
+- `community.docker` Collection
+
+## Einbindung
+
+```yaml
+- hosts: all
+  become: true
+  user: admin
+  roles:
+    - role: hawser
+```
+
+```bash
+ansible-playbook -i inventory/dmc12.yml playbooks/upgrade-hawser.yml
+```
+
+## Funktionsweise
+
+`tasks/main.yml` importiert `tasks/update-stack.yml`:
+
+1. **Docker-Host-Info sammeln** – prüft, ob Docker erreichbar ist
+   (`community.docker.docker_host_info`). Bei Fehler werden nachfolgende
+   Tasks übersprungen.
+2. **Compose-Datei prüfen** – `stat` auf `<hawser_compose_dir>/docker-compose.yml`.
+   Fehlt die Datei, wird kein Update durchgeführt (Bestandsschutz).
+3. **Compose-Datei ausliefern** – Template `docker-compose.yml.j2` wird nur
+   geschrieben, wenn Docker erreichbar UND bereits eine Compose-Datei
+   vorhanden ist.
+4. **Stack aktualisieren** – `community.docker.docker_compose_v2` mit
+   `pull: always` und `state: present` zieht die neuesten Images und
+   erneuert die Container.
+
+## Variablen
+
+| Variable                       | Typ    | Default        | Beschreibung                                              |
+|--------------------------------|--------|----------------|-----------------------------------------------------------|
+| `hawser_project_name`          | string | `hawser`       | Name des Docker-Compose-Projekts                          |
+| `hawser_compose_dir`           | string | `/opt/hawser`  | Verzeichnis der Compose-Datei auf dem Zielhost            |
+| `hawser_port`                  | string | `2376`         | Freigegebener Port des Hawser-Agents (Host-Port)          |
+| `hawser_stacks_volume`         | string | `hawser_stacks`| Name des externen Docker-Volumes für Stack-Dateien       |
+| `hawser_allow_insecure_no_auth`| bool   | `true`         | `ALLOW_INSECURE_NO_AUTH` – Standard-Mode ohne Token      |
+
+> **Achtung:** `hawser_allow_insecure_no_auth: true` erlaubt den Betrieb ohne
+> Token-Authentifizierung auch auf Nicht-Loopback-Adressen. Nur setzen, wenn
+> das Netzwerk durch andere Maßnahmen (Firewall, VPN) abgesichert ist.
+
+## Templates
+
+| Template               | Ziel                                       |
+|------------------------|--------------------------------------------|
+| `docker-compose.yml.j2`| `<hawser_compose_dir>/docker-compose.yml`  |
+
+Das Template konfiguriert den Hawser-Container mit Socket-Mount, externem
+Volume, Port-Mapping, Environment-Variablen, `image: ghcr.io/finsys/hawser:latest`
+und `restart: always`.
+
+## Handler
+
+Keine Handler erforderlich – `docker compose up -d` ersetzt laufende Container
+eigenständig.
+
+## Tags
+
+Die Rolle vergibt keine eigenen Tags.
+
+## Abhängigkeiten
+
+- `community.docker` Collection (`docker_host_info`, `docker_compose_v2`)
+- Vorherige Installation der `docker`-Rolle
+
+## Hinweise
+
+- Die Rolle **erzeugt keine Neuinstallation** – die Compose-Datei wird nur
+  geschrieben, wenn bereits eine existiert. So wird verhindert, dass Hawser
+  versehentlich auf Hosts ausgebracht wird, auf denen es nicht vorgesehen ist.
+- Das externe Volume `hawser_stacks` muss vor dem ersten Start manuell
+  erstellt werden (`docker volume create hawser_stacks`).
+- `pull: always` sorgt für aktuelle Images, erfordert aber Internetzugang
+  zum ghcr.io-Registry.