Major site overhaul: reflect all current product features + logo + Stripe Payment Links
Homepage: AI-powered hero, 9 feature cards (AI Intent Router, MCP Server, Security Center, Fleet Management, Service Discovery, Plugin System), expanded comparison table (7→13 rows), Smart Wizard in How It Works Features page: Complete rewrite — 8 feature sections led by AI-Powered Self-Hosting, Free vs Premium comparison grid Pricing page: Fixed broken Stripe checkout (was 503 stub). Subscribe button now uses Stripe Payment Links. Core tier lists all 18 features. All 7 docs pages: Updated to reflect current architecture (AI, MCP, Security Center, SDK, Caddyfile-as-Code, Service Discovery, etc.) About page: AI-Native value prop, updated tech stack, by-the-numbers Navbar: Fixed broken #anchor links → proper routes, added DashCaddy logo AppShowcase: 50+ → 76+ templates Logo: Dark + light versions deployed, wired into navbar/footer/favicon
This commit is contained in:
Krystie
@@ -8,30 +8,88 @@ export default function DocsTroubleshootingPage() {
|
||||
<Navbar />
|
||||
<DocsLayout
|
||||
title="Troubleshooting"
|
||||
intro="Because DashCaddy sits across runtime, DNS, reverse proxy, certificates, and dashboard state, the fastest way to debug it is layer by layer instead of guessing."
|
||||
intro="Because DashCaddy sits across runtime, DNS, reverse proxy, certificates, and dashboard state, the fastest way to debug it is layer by layer instead of guessing. This guide walks each layer with the common failures and fixes."
|
||||
>
|
||||
<h2>Debug order</h2>
|
||||
<h2>Health check endpoints</h2>
|
||||
<p>
|
||||
Start every investigation with the built-in probes — they tell you whether the platform itself is healthy and
|
||||
whether its dependencies are wired up:
|
||||
</p>
|
||||
<ul>
|
||||
<li><code>/healthz</code> — <strong>liveness</strong>. Returns 200 if the DashCaddy process is up.</li>
|
||||
<li><code>/readyz</code> — <strong>readiness</strong>. Returns 200 only when DashCaddy can serve traffic, including connectivity to Docker, Caddy, and DNS where configured.</li>
|
||||
</ul>
|
||||
<pre className="mt-4 overflow-x-auto rounded-lg border border-surface-700/50 bg-surface-950/80 p-4 text-sm"><code>{`curl -s -o /dev/null -w "%{http_code}" https://dashcaddy-host/healthz
|
||||
curl -s -o /dev/null -w "%{http_code}" https://dashcaddy-host/readyz`}</code></pre>
|
||||
<p>
|
||||
If <code>/healthz</code> fails, the DashCaddy process itself is down. If <code>/healthz</code> passes but
|
||||
<code>/readyz</code> fails, a dependency (Docker socket, Caddy Admin API, or Technitium DNS) is unreachable.
|
||||
</p>
|
||||
|
||||
<h2>The debug order</h2>
|
||||
<p>Work bottom-up through the stack so you isolate the failing layer:</p>
|
||||
<ol>
|
||||
<li>backend process or container</li>
|
||||
<li>service port reachability</li>
|
||||
<li>reverse proxy route</li>
|
||||
<li>DNS</li>
|
||||
<li>certificate trust</li>
|
||||
<li>dashboard/API visibility</li>
|
||||
<li><strong>Backend container</strong> — is it running and healthy?</li>
|
||||
<li><strong>Backend port</strong> — is the service listening and reachable on the host?</li>
|
||||
<li><strong>Reverse proxy route</strong> — did Caddy apply the route correctly?</li>
|
||||
<li><strong>DNS</strong> — does the hostname resolve to the right host?</li>
|
||||
<li><strong>Certificate trust</strong> — does the client trust the CA?</li>
|
||||
<li><strong>Dashboard / API state</strong> — does DashCaddy reflect reality?</li>
|
||||
</ol>
|
||||
|
||||
<h2>Common failures</h2>
|
||||
<h2>DNS issues</h2>
|
||||
<ul>
|
||||
<li>service is down even though the dashboard is reachable</li>
|
||||
<li>internal HTTPS shows warnings because DashCA trust is missing</li>
|
||||
<li>DNS automation fails due to API token or zone issues</li>
|
||||
<li>Caddy changes are not applying because Admin API is unavailable</li>
|
||||
<li>Premium features do not unlock because license validation is failing</li>
|
||||
<li><strong>Symptom</strong>: hostname does not resolve, or resolves to the wrong address.</li>
|
||||
<li><strong>Check</strong>: is Technitium DNS running and is the DashCaddy API token valid?</li>
|
||||
<li><strong>Check</strong>: is the record present in the correct zone? DNS automation fails silently when the zone name is wrong.</li>
|
||||
<li><strong>Check</strong>: is the client using Technitium as its resolver? Public resolvers will not know about internal zones.</li>
|
||||
<li><strong>Fix</strong>: re-run the DNS step from the service's action menu, or recreate the record manually and let DashCaddy reconcile.</li>
|
||||
</ul>
|
||||
<pre className="mt-4 overflow-x-auto rounded-lg border border-surface-700/50 bg-surface-950/80 p-4 text-sm"><code>{`# Verify resolution against the Technitium resolver directly
|
||||
dig @technitium-host media.lab
|
||||
nslookup media.lab technitium-host`}</code></pre>
|
||||
|
||||
<h2>TLS / certificate problems</h2>
|
||||
<ul>
|
||||
<li><strong>Symptom</strong>: browser shows a certificate warning or <code>NET::ERR_CERT_AUTHORITY_INVALID</code>.</li>
|
||||
<li><strong>Cause</strong>: the client does not trust Caddy's internal CA / DashCA root certificate.</li>
|
||||
<li><strong>Fix</strong>: download the root certificate from the <strong>DashCA</strong> page and install it as a trusted root CA on the client device. Every modern OS and browser has a slightly different import flow — the DashCA page includes per-platform instructions.</li>
|
||||
<li><strong>Cause</strong>: certificate issuance failed because the Caddy Admin API was unreachable at deploy time.</li>
|
||||
<li><strong>Fix</strong>: confirm the Caddy Admin API is reachable, then redeploy or re-trigger TLS for the service.</li>
|
||||
</ul>
|
||||
|
||||
<h2>Reverse proxy debugging (Caddy)</h2>
|
||||
<ul>
|
||||
<li><strong>Symptom</strong>: service is up and DNS resolves, but the URL returns 502/504 or does not route.</li>
|
||||
<li><strong>Check</strong>: is the Caddy Admin API reachable from the DashCaddy API server?</li>
|
||||
<li><strong>Check</strong>: does the Caddy route point at the correct upstream host:port? Use the Caddyfile-as-Code view to inspect the generated config.</li>
|
||||
<li><strong>Check</strong>: Caddy logs — <code>docker logs caddy</code> or your Caddy service logs — for upstream connection errors.</li>
|
||||
<li><strong>Fix</strong>: re-apply the route from the service's action menu; DashCaddy will reconcile the Caddy configuration atomically.</li>
|
||||
</ul>
|
||||
|
||||
<h2>Container health</h2>
|
||||
<ul>
|
||||
<li><strong>Symptom</strong>: service shows <em>Unhealthy</em> or <em>Down</em> on the dashboard.</li>
|
||||
<li><strong>Check</strong>: <code>docker ps -a</code> and <code>docker logs <container></code> for crash loops or misconfiguration.</li>
|
||||
<li><strong>Check</strong>: does the container's healthcheck (if defined) pass? DashCaddy surfaces container healthchecks in the UI.</li>
|
||||
<li><strong>Check</strong>: are volumes and environment variables correct? Bad secrets are the most common cause of immediate exits.</li>
|
||||
</ul>
|
||||
|
||||
<h2>Common gotchas</h2>
|
||||
<ul>
|
||||
<li><strong>Service is down even though the dashboard is reachable</strong> — the dashboard and the service are different containers; always check the backend container directly.</li>
|
||||
<li><strong>DNS automation fails silently</strong> — usually an expired or wrong-scope Technitium API token, or a mismatched zone name.</li>
|
||||
<li><strong>Caddy changes are not applying</strong> — the Admin API is unavailable or the generated config is invalid; check the Caddyfile-as-Code view for errors.</li>
|
||||
<li><strong>Premium features do not unlock</strong> — license validation is failing; verify the license key and that the host can reach the licensing server, and remember the one-active-machine limit.</li>
|
||||
<li><strong>Internal HTTPS still warns after install</strong> — the root CA must be trusted on <em>each</em> client device, not just the server.</li>
|
||||
<li><strong>WebSocket live updates stall</strong> — a reverse proxy or firewall in front of DashCaddy may be dropping the upgrade; allow WebSocket upgrades on the DashCaddy route.</li>
|
||||
</ul>
|
||||
|
||||
<h2>Mindset</h2>
|
||||
<p>
|
||||
Most DashCaddy problems are really one dependency layer failing while the others are healthy. Debugging that dependency chain is the right way to recover quickly.
|
||||
Most DashCaddy problems are really one dependency layer failing while the others are healthy. Use the health
|
||||
endpoints to localize, then walk the debug order. Fixing the right layer first is always faster than
|
||||
reloading the whole stack.
|
||||
</p>
|
||||
</DocsLayout>
|
||||
<Footer />
|
||||
|
||||
Reference in New Issue
Block a user