---
id: MOD-006
type: module
status: active
title: Hawser Role
created: 2026-09-09
updated: 2026-09-09
tags: [module, hawser, docker, ansible]
related: [MOD-002, REQ-005]
source_paths:
- roles/hawser/
confidence: confirmed
---

# Hawser Role

## Responsibility

Update the Hawser Docker Compose stack on a host that already runs Docker.

## Source Paths

- `roles/hawser/tasks/main.yml` → `update-stack.yml`
- Template: `roles/hawser/templates/docker-compose.yml.j2`
- Handlers: `roles/hawser/handlers/main.yml`

## Public Interfaces

- Playbook: `playbooks/upgrade-hawser.yml`
- Key variables: `hawser_project_name` (hawser),
  `hawser_compose_dir` (/opt/hawser), `hawser_port` (2376),
  `hawser_stacks_volume` (hawser_stacks),
  `hawser_allow_insecure_no_auth` (true - documented as requiring an
  otherwise secured network).

## Important Flows

1. Gather Docker host info (`community.docker.docker_host_info`,
   `ignore_errors: true`).
2. Require existing compose file at `<hawser_compose_dir>/docker-compose.yml`;
   re-render it from the template.
3. `community.docker.docker_compose_v2` with `state: present`,
   `pull: always` to pull latest images and recreate the stack.

## Dependencies

- Requires Docker on the target (role skips gracefully when Docker is not
  reachable). Collection: `community.docker`.

## Tests

- None automated.

## Notes For Agents

- `hawser_allow_insecure_no_auth: true` allows token-less standard mode on
  non-loopback addresses; treat as a deliberate, documented trade-off.