From 58922bee537c7edc9c59a0970ced4b3ce6797f76 Mon Sep 17 00:00:00 2001
From: Marcel <marcel@familienarchiv>
Date: Mon, 11 May 2026 23:14:35 +0200
Subject: [PATCH] docs(ci): add Troubleshooting section for Reload Caddy
 failures

Covers the three failure modes Sara flagged: Caddy stopped (explicit
systemctl error), symlink missing/mis-pointed (silent reload, stale
smoke test), and Docker socket / nsenter unavailable (container error).
Each failure mode includes symptoms and recovery steps.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 docs/infrastructure/ci-gitea.md | 50 +++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/docs/infrastructure/ci-gitea.md b/docs/infrastructure/ci-gitea.md
index d54adcfa..017d6ba2 100644
--- a/docs/infrastructure/ci-gitea.md
+++ b/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