Troubleshooting

Diagnose and fix common problems: one page per symptom family, written so the fix is reachable without reading the rest of the docs first.

In this section

• Build Failures: promotion blocked, render errors, timeouts and write-budget bursts; where the reason text and the “promote anyway” control live.
• CSS Blocked (SRI): when the admin refuses to load the stylesheet and why the integrity hash is content-derived.
• Port Conflicts: which port belongs to which layer, who owns it, and how to move it cleanly.
• Login & Auth Issues: lockouts, expiry, suspensions, session revocation.
• Redirects & 404s: why a static site 404s where the CMS would respond, and the redirect formats’ rules.
• FAQ: the frequently-asked roundup (passwords, builds, lockouts, API keys, first-boot setup).

The habit that solves most of it

Two surfaces answer most questions before symptom-hunting:

• The build history (Builds in the admin): the last 100 runs with per-check reasons, captured output, and the exact refusal text for blocked promotes.
• The journal (journalctl -u chinaski@<N>), every service-level message including login lockouts, deploy failures, and webhook outcomes.

/health (multi-check with per-check details) and /api/health (summary for monitors) close the loop: when neither reports healthy, the problem is infrastructural rather than content.