# REPORT — crafty-controller healthcheck fix

**Date:** 2026-06-26 · **Repo:** `app-catalog-felhom.eu` (catalog-only) · **Commit:** `68ce009`
**Guest:** 9201 (`demo-felhom`) on `felhom-pve` · **Controller:** v0.82.0 (unchanged)

## Scope
Catalog-only fix of the crafty-controller healthcheck (no Go change, no controller/agent rebuild, no
version bump). Built on the prior diagnosis (root cause: image has no `curl`).

## Files changed (2)
- `templates/crafty-controller/docker-compose.yml` — Docker healthcheck `test` `curl` → python3 TLS
  socket probe; `start_period` 30s → 60s.
- `templates/crafty-controller/.felhom.yml` — controller-side probe `type: http` → `type: tcp` (8443
  is TLS-only).

Effective new Docker healthcheck:
```
["CMD","/usr/bin/python3","-c","import socket,ssl; ssl._create_unverified_context().wrap_socket(socket.create_connection(('127.0.0.1',8443),timeout=3)).close()"]
interval 30s · timeout 5s · retries 3 · start_period 60s
```

## Two root causes (both required)
1. **Docker probe** used `curl`, absent in `crafty-4:4.4.8` (`exec: "curl": not found`, FailingStreak 150).
2. **Controller-side probe** did plaintext `http://…:8443` against a TLS port → `HealthProbe.Healthy=false`
   → `manager.go:471` overrides `running` back to `unhealthy`. Fixing only #1 would have flipped back at
   the next controller probe. Verified empirically.

## Deploy path (real flow)
1. Commit + push to `main` (`68ce009`).
2. Controller git-sync via `POST /api/sync` (Host: felhom.demo-felhom.eu) → `[sync] Updated
   crafty-controller/docker-compose.yml` + `.felhom.yml`; `app.yaml` untouched.
3. Recreate via the UI update path `POST /api/stacks/crafty-controller/update` (`docker compose up -d`;
   restart would not pick up a healthcheck change).

## Verification (acceptance gate)
- **New healthcheck live:** `docker inspect .Config.Healthcheck` = python3 cmd, `StartPeriod` 60s.
- **Executes + passes:** `State.Health` → `Status: healthy`, `FailingStreak: 0`, Log `ExitCode: 0`.
- **Controller-side probe clear:** `GET /api/stacks/crafty-controller` → `health_probe.healthy: true`,
  `details: [{type: tcp, target: :8443, healthy: true, latency: 5ms}]`; http-vs-TLS `[WARN] Health probe
  crafty-controller …` entries stopped at the 07:46 sync, none after.
- **Green + stable:** `Up 3 minutes (healthy)`, state `running` across a probe cycle (override gone).
- **Route un-withheld:** Traefik now publishes `crafty-controller@docker` (in its access log) — the
  `routeUnpublished` / "URL nem elérhető" condition is resolved.

## Open item (separate task — NOT this fix)
Public URL `https://minecraft.demo-felhom.eu` still returns **502**. Distinct, pre-existing bug exposed
by the now-published route: Traefik proxies `http://172.18.0.6:8443` to Crafty's **HTTPS-only**
self-signed backend (access log: `502 … "crafty-controller@docker" "http://172.18.0.6:8443"`). Crafty
serves no plain-HTTP port (only 8443 listens). A working fix needs Traefik HTTPS backend
(`scheme=https`) **plus** a `serversTransport` with `insecureSkipVerify` for the self-signed cert —
the latter cannot be set via Docker labels in Traefik v3, so it requires the controller-generated
Traefik config / felhom-controller Go (out of this catalog-only task). Investigation of fix options is
in progress per request; plan to follow before any implementation.

## Observations (documented, not acted on)
1. `probeHTTP` can only target `http://` backends — no TLS support. A general fix would teach it
   `https`/honor a `scheme` field so future TLS apps can use `type: http`/`api` checks. Own task.
2. Catalog-wide audit: other apps whose Docker healthcheck uses a possibly-absent binary
   (`curl`/`wget`), or whose `.felhom.yml` uses `type: http` against a TLS port. Own task.