# 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.