docs/infrastructure/ci-gitea.md

@@ -58,6 +58,56 @@ ls -la /etc/caddy/Caddyfile
 # Expected: lrwxrwxrwx ... /etc/caddy/Caddyfile -> /opt/familienarchiv/infra/caddy/Caddyfile
 ```
 
+### Troubleshooting: Reload Caddy step fails
+
+**Failure mode 1 — Caddy is stopped**
+
+Symptom in CI log:
+```
+Failed to reload caddy.service: Unit caddy.service is not active.
+```
+
+Recovery:
+```bash
+ssh root@<vps>
+systemctl start caddy
+systemctl status caddy   # confirm Active: active (running)
+```
+
+Re-run the workflow via Gitea Actions → "Re-run workflow".
+
+**Failure mode 2 — Caddyfile symlink is missing or mis-pointed**
+
+This failure is silent — `systemctl reload caddy` exits 0 but Caddy reloads whatever `/etc/caddy/Caddyfile` currently resolves to. The smoke test may then pass against stale config.
+
+Symptom: smoke test fails on the HSTS value or the `/actuator/health → 404` check despite the Reload Caddy step succeeding.
+
+Diagnosis:
+```bash
+ssh root@<vps>
+ls -la /etc/caddy/Caddyfile
+# Should be: lrwxrwxrwx ... /etc/caddy/Caddyfile -> /opt/familienarchiv/infra/caddy/Caddyfile
+```
+
+Recovery if symlink is wrong or missing:
+```bash
+ln -sf /opt/familienarchiv/infra/caddy/Caddyfile /etc/caddy/Caddyfile
+systemctl reload caddy
+```
+
+**Failure mode 3 — nsenter / Docker socket unavailable**
+
+Symptom in CI log:
+```
+docker: Cannot connect to the Docker daemon at unix:///var/run/docker.sock.
+```
+or
+```
+nsenter: failed to execute /bin/systemctl: No such file or directory
+```
+
+The first error means the Docker socket is not mounted into the job container — check `valid_volumes` in `/root/docker/gitea/runner-config.yaml` on the VPS. The second means the Alpine image is running but cannot enter the host mount namespace; verify `--privileged` and `--pid=host` are both present in the workflow step.
+
 ---
 
 ## Gitea vs GitHub Actions Differences