91 lines
4.7 KiB
Markdown
91 lines
4.7 KiB
Markdown
# Runbook — publishing a service on mf01
|
|
|
|
mf01 publishes HTTP services as `https://<svc>.mf01.makerfloss.eu`. TLS
|
|
terminates on the **makerfloss VPS**; the VPS proxies `*.mf01` over `wg1` to
|
|
mf01's internal Traefik (`10.13.0.8:80`), which routes by Host label to the
|
|
container.
|
|
|
|
- Design: `AnsibleBaobabV4/docs/superpowers/specs/2026-06-09-mf01-service-publishing-design.md`
|
|
- Plan: `AnsibleBaobabV4/docs/superpowers/plans/2026-06-09-mf01-service-publishing.md`
|
|
- Built and verified live 2026-06-09 (first service: `whoami.mf01.makerfloss.eu`).
|
|
|
|
## How a request flows
|
|
|
|
```
|
|
browser ─https─▶ <svc>.mf01.makerfloss.eu (DNS *.mf01 A → 88.99.32.236)
|
|
─▶ VPS Traefik :443 (wildcard cert *.mf01.makerfloss.eu, TLS ends here)
|
|
─▶ plain HTTP over wg1 ─▶ mf01 Traefik 10.13.0.8:80
|
|
─▶ container (routed by Host label)
|
|
```
|
|
|
|
The VPS side is configured **once** (in `host_vars/makerfloss.yml`):
|
|
`traefik_wildcard_sets` (anchors the `*.mf01` DNS-01 cert), a
|
|
`traefik_extra_dynamic_files` catch-all router → `http://10.13.0.8:80`, and the
|
|
`mf01` / `*.mf01` A records. **You never touch the VPS to add a service.**
|
|
|
|
mf01 is configured once (in `host_vars/mf01.yml`): internal Traefik
|
|
(`traefik_acme_enabled: false`, `traefik_bind_address: 10.13.0.8`),
|
|
`traefik_zone: mf01.makerfloss.eu`, and host-wide
|
|
`container_traefik_overrides: {entrypoints: [web], tls: false, certresolver: ""}`.
|
|
|
|
## Add a new service
|
|
|
|
1. Enable a container role on mf01 in `host_vars/mf01.yml`, e.g.:
|
|
```yaml
|
|
container_<svc>_enabled: true
|
|
```
|
|
Its router auto-publishes as `<container_name>.mf01.makerfloss.eu` because
|
|
`traefik_zone` is `mf01.makerfloss.eu` and the host-wide
|
|
`container_traefik_overrides` force the plain `web` entrypoint with no TLS.
|
|
2. Deploy (note: the tag is the role's short name, e.g. `whoami`, not
|
|
`container-whoami`):
|
|
```bash
|
|
cd ~/Projects/AnsibleBaobabV4
|
|
.venv/bin/ansible-playbook play_containers.yml --limit mf01 -t <svc>
|
|
```
|
|
3. Live at `https://<container_name>.mf01.makerfloss.eu` — no DNS, cert, or VPS
|
|
change (covered by the wildcard cert + catch-all route). Verify:
|
|
```bash
|
|
curl -s https://<container_name>.mf01.makerfloss.eu
|
|
```
|
|
|
|
To use a hostname other than the container's default name, set that service's
|
|
`hostnames` via its own `container_traefik_overrides` (do **not** put hostnames
|
|
in the host-wide dict — that would force every service to the same name).
|
|
|
|
## Publishing under a bare hostname (not `*.mf01`)
|
|
|
|
Done for `laser.makerfloss.eu` on 2026-08-16 (`baobab.laser-course` on mf01).
|
|
The wildcard cert/route only covers `*.mf01.makerfloss.eu`, so a bare name
|
|
needs **one** VPS-side addition: a `Host()` file router in
|
|
`traefik_extra_dynamic_files` (`host_vars/makerfloss.yml`, see
|
|
`laser-delegate.yml`) pointing at `http://10.13.0.8:80` with
|
|
`tls.certResolver: letsencrypt` — a `Host()` router triggers DNS-01 issuance for
|
|
exactly that name (took ~2 min). Plus the `A` record for the name → VPS. On
|
|
mf01, set the service's own `<svc>_traefik_overrides.hostnames`; if that role
|
|
sets `container_traefik_overrides` at role-vars level (laser-course does,
|
|
gcodeoverlay doesn't), repeat `entrypoints: [web]`, `tls: false`,
|
|
`certresolver: ""` there because it outranks the host-wide dict. Auth
|
|
middlewares from container labels are enforced by mf01's Traefik and work
|
|
unchanged. Deploy mf01 first, then `--limit makerfloss -t traefik`.
|
|
|
|
## Reach / management
|
|
|
|
- Ansible reaches mf01 at its stable wg IP `10.13.0.8` via ProxyJump through the
|
|
VPS (`ansible_host: 10.13.0.8`, `ProxyJump="sjat@makerfloss.eu:7576"`).
|
|
- Shell: `ssh -J sjat@makerfloss.eu:7576 -p 7576 sjat@10.13.0.8`.
|
|
|
|
## Troubleshooting
|
|
|
|
| Symptom | Check |
|
|
|---|---|
|
|
| `https://<svc>.mf01...` → 404, valid cert | Request reached mf01 Traefik but no router matches. Confirm the container is up (`docker ps` on mf01) and has the `traefik.http.routers.<svc>.rule=Host(...)` label. |
|
|
| `tls_verify != 0` / cert error | VPS Traefik isn't serving the `*.mf01` cert. Check `docker logs traefik` on the VPS for ACME (`acme: ... mf01`), and that `/srv/traefik/config/dynamic/mf01-delegate.yml` **parses** (a YAML error there breaks the whole file provider — keep regex rules single-quoted). |
|
|
| 502/504 from the VPS | wg1 tunnel down or mf01 Traefik down. Check `wg show wg1` on the VPS (mf01 = `10.13.0.8`) and the traefik container on mf01. |
|
|
| Service restricted access wanted | The `internal-only@file` middleware lives on the **VPS** Traefik; a restricted service must be routed VPS-side or use an mf01-side allowlist middleware (future work). |
|
|
|
|
## Known limitation
|
|
|
|
`container_traefik_overrides` is host-wide on mf01 (correct for entrypoint/tls,
|
|
which are constant). Per-service **hostnames** must come from each service's own
|
|
role override, not the host-wide dict.
|