sami7777/dashcaddy.net
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: docs pages, navbar, footer updates from QA sprint

Browse Source
This commit is contained in:
Krystie committed 2026-08-12 17:34:14 -07:00
1 parent a3648f66d8
commit ee4066f19c
6 files changed
+1178 -200
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

src/app/docs/integrations/page.tsx
+245 -38
View File
@@ -10,81 +10,288 @@ export default function DocsIntegrationsPage() {
title="Infrastructure Integrations"
intro="DashCaddy is most valuable when its supporting integrations are healthy. This guide explains each layer it expects to work with, what it does, and how the pieces fit together into a single control plane."
>
<h2>Docker</h2>
<p>
Docker (and Docker Compose) is the runtime foundation for deployment workflows, container lifecycle actions,
service discovery, and template-based launches. DashCaddy talks to the Docker daemon to start, stop, restart,
inspect, and adopt containers, and to deploy the 76+ one-click application templates. Optional Docker Swarm
support (Premium) extends the same model across multiple nodes.
DashCaddy is not a monolith. It is an orchestration layer that drives several independent infrastructure
components — a container runtime, a reverse proxy, a DNS server, a certificate authority, a private network,
a metrics pipeline, and an AI surface. Each integration is swappable, observable, and independently debuggable.
When you understand what each layer is responsible for, you can pinpoint failures in minutes instead of guessing.
</p>
<p>
This guide walks every integration in depth: what it does, how DashCaddy talks to it, the configuration it
expects, and a code example where relevant. Read it end-to-end once, then come back to specific sections when
something goes wrong. For a quick diagnostic flow, see the <a href="/docs/troubleshooting">Troubleshooting</a> guide.
</p>
<h2>Caddy — reverse proxy &amp; HTTPS</h2>
<h2>Docker — container runtime</h2>
<p>
Caddy is the reverse proxy and automatic HTTPS layer. DashCaddy communicates with the <strong>Caddy Admin API</strong>
to create, update, and remove routes, and to trigger certificate issuance. Caddy&apos;s built-in internal CA
auto-generates and renews certificates for every published service.
Docker (and Docker Compose) is the runtime foundation for every deployment workflow, container lifecycle action,
service discovery sweep, and template-based launch. DashCaddy communicates with the Docker daemon over the
Unix socket (<code>/var/run/docker.sock</code>) to start, stop, restart, inspect, and adopt containers, and to
deploy the <strong>76+ one-click application templates</strong> from the catalog.
</p>
<p>
The daemon connection is established at startup. If the socket is missing or permissioned for a different user,
DashCaddy&apos;s <code>/readyz</code> probe will fail immediately — a fast signal that the runtime layer is broken.
During the <strong>Smart Defaults Wizard</strong>, DashCaddy probes the socket, reports the Docker version, and
suggests socket paths if the default is not found.
</p>
<p>
Optional <strong>Docker Swarm</strong> support (Premium) extends the same model across multiple nodes. When
Swarm mode is enabled, DashCaddy switches from single-container operations to service-level operations, managing
placement, replicas, and rolling updates across the cluster. See <a href="/docs/premium">Premium Features</a>.
</p>
<pre className="mt-4 overflow-x-auto rounded-lg border border-surface-700/50 bg-surface-950/80 p-4 text-sm"><code>{`# Verify the Docker socket DashCaddy will use
docker version
ls -l /var/run/docker.sock
# The DashCaddy container needs the socket mounted:
docker run -d \\
-v /var/run/docker.sock:/var/run/docker.sock \\
-p 3000:3000 \\
ghcr.io/dashcaddy/dashcaddy:latest`}</code></pre>
<blockquote className="border-l-4 border-brand-500/50 bg-brand-500/5 p-4 rounded-r-lg">
<p className="text-surface-300">
<strong className="text-brand-400">Note:</strong> Mounting the Docker socket grants full container control.
In production, run DashCaddy behind Tailscale or a firewall so the dashboard is not exposed to the public
internet.
</p>
</blockquote>
<h2>Caddy — reverse proxy &amp; automatic HTTPS</h2>
<p>
Caddy is the reverse proxy and automatic HTTPS layer. Every service you publish through DashCaddy gets a Caddy
route that terminates TLS and proxies traffic to the upstream container. DashCaddy communicates with the
<strong> Caddy Admin API</strong> (default <code>localhost:2019</code>) to create, update, and remove routes,
and to trigger certificate issuance on demand.
</p>
<p>
Caddy&apos;s built-in internal CA auto-generates and renews certificates for every published service. For
public domains, Caddy can also use ACME (Let&apos;s Encrypt / ZeroSSL) automatically. The choice between
internal and public CA is made per-service at publish time, so you can mix internet-facing and lab services
on the same host without conflict.
</p>
<h3>Caddyfile-as-Code</h3>
<p>
Instead of hand-editing Caddyfiles, DashCaddy exposes a <strong>visual Caddyfile-as-Code builder</strong>. You
describe the desired route — hostname, upstream, TLS options, headers, redirects — and DashCaddy generates the
valid Caddy configuration and applies it atomically through the Admin API. Configuration is versioned and
reviewable, so changes are auditable and reversible.
describe the desired route — hostname, upstream, TLS options, headers, redirects, compression — and DashCaddy
generates the valid Caddy configuration and applies it atomically through the Admin API. Configuration is
versioned and reviewable, so every change is auditable and reversible.
</p>
<p>
The generated config is rendered in the service&apos;s <strong>Caddyfile-as-Code view</strong>, so you can
inspect exactly what Caddy will receive before it is applied. If a route misbehaves, compare the rendered config
against your expectation. Invalid configs are rejected before they reach Caddy, preventing the proxy from
reloading into a broken state.
</p>
<pre className="mt-4 overflow-x-auto rounded-lg border border-surface-700/50 bg-surface-950/80 p-4 text-sm"><code>{`# Example generated Caddyfile (internal CA, lab hostname)
media.lab {
tls internal
<h2>Technitium DNS</h2>
encode zstd gzip
reverse_proxy localhost:8096 {
header_up X-Forwarded-Host {host}
header_up X-Real-IP {remote_host}
}
header {
Strict-Transport-Security "max-age=31536000"
X-Content-Type-Options nosniff
}
}`}</code></pre>
<h2>Technitium DNS — DNS automation</h2>
<p>
Technitium DNS is the DNS automation target for record creation and removal. When you deploy or adopt a service,
DashCaddy creates the corresponding A/CNAME record through the Technitium API so the new hostname resolves
immediately. Removing a service cleans up the record automatically.
DashCaddy creates the corresponding A or CNAME record through the Technitium REST API so the new hostname
resolves immediately. Removing a service cleans up the record automatically — no orphaned DNS entries.
</p>
<p>
DashCaddy needs three pieces of information to drive Technitium: the server URL, an API token with write access
to the target zone, and the zone name itself. All three are configured during the Smart Defaults Wizard or
later under <strong>Settings → DNS</strong>. A common failure mode is a token with the wrong scope — it can
read records but not create them — which fails silently. Always verify the token can write to the zone you
intend to use.
</p>
<p>
Internal zones (e.g. <code>.lab</code>) only resolve if the client uses Technitium as its resolver. Public
resolvers like 8.8.8.8 will not know about them. For remote clients, either point their DNS at Technitium
directly or use <strong>Tailscale</strong> with a MagicDNS / split-DNS setup.
</p>
<pre className="mt-4 overflow-x-auto rounded-lg border border-surface-700/50 bg-surface-950/80 p-4 text-sm"><code>{`# Create a record directly via the Technitium API (debugging)
curl -X POST "http://technitium-host:5380/api/zones/records/add" \\
-d "token=***" \\
-d "zone=lab" \\
-d "domain=media.lab" \\
-d "type=A" \\
-d "ipAddress=192.168.1.50"
# Verify the record resolves through Technitium
dig @technitium-host media.lab +short`}</code></pre>
<h2>DashCA — internal certificate authority</h2>
<p>
DashCA is the certificate distribution system that makes internal HTTPS practical. Caddy&apos;s internal CA
issues certificates automatically; DashCA provides the distribution page where you download the root
certificate and install it as a trusted CA across your devices. Once trusted, every internal service is served
over valid HTTPS with no browser warnings.
issues certificates automatically for <code>.lab</code> and other private hostnames; DashCA provides the
distribution page where you download the root certificate and install it as a trusted CA across your devices.
Once trusted, every internal service is served over valid HTTPS with no browser warnings.
</p>
<p>
The root certificate must be installed on <strong>each client device</strong> that will access internal
services — not just the server. A macOS laptop, a Windows desktop, and an Android phone each need the cert
installed separately. The DashCA page includes per-platform instructions (macOS Keychain, Windows certmgr,
Linux <code>update-ca-certificates</code>, and mobile profiles) to make this straightforward.
</p>
<p>
After installing the root CA, restart your browser or clear its certificate cache. Chrome and Firefox maintain
separate trust stores on some platforms; Firefox may need the import done from within its own settings.
</p>
<h2>Tailscale — private access</h2>
<p>
DashCaddy fits naturally into private access patterns with <strong>Tailscale</strong>. Services can be published
only on a Tailnet, keeping them off the public internet while still benefiting from DashCaddy&apos;s DNS, proxy,
and TLS automation. This is ideal for home labs and internal team tools.
and TLS automation. This is ideal for home labs, internal team tools, and any service that should never be
internet-facing.
</p>
<p>
The typical setup runs Tailscale on the DashCaddy host, advertises the host on the Tailnet, and optionally
enables MagicDNS so Tailnet hostnames resolve without a separate DNS server. Combine with Technitium split-DNS
for the most seamless experience: Technitium handles <code>.lab</code> zones for Tailnet clients, while public
domains resolve normally.
</p>
<pre className="mt-4 overflow-x-auto rounded-lg border border-surface-700/50 bg-surface-950/80 p-4 text-sm"><code>{`# Install and authenticate Tailscale on the DashCaddy host
curl -fsSL https://tailscale.com/install.sh | sh
tailscale up --advertise-routes=192.168.1.0/24 --accept-routes
<h2>Prometheus &amp; Grafana — metrics</h2>
# Verify the host is on the Tailnet
tailscale status
tailscale ip
# From another Tailnet device, reach the service directly
curl -k https://dashcaddy-host.tailnet-name.ts.net/media.lab`}</code></pre>
<blockquote className="border-l-4 border-brand-500/50 bg-brand-500/5 p-4 rounded-r-lg">
<p className="text-surface-300">
<strong className="text-brand-400">Tip:</strong> If you publish services only on the Tailnet, set Caddy to
bind to the Tailscale interface IP rather than <code>0.0.0.0</code>. This guarantees the service is
unreachable from the LAN even if the firewall is misconfigured.
</p>
</blockquote>
<h2>Prometheus &amp; Grafana — metrics &amp; observability</h2>
<p>
DashCaddy exports metrics in Prometheus format at <code>/metrics</code>, including service health, container
status, request counts, and system indicators. Point your Prometheus scraper at the endpoint and build
Grafana dashboards on top for long-term observability and alerting.
status, request counts, certificate expiry, and system resource indicators. Point your Prometheus scraper at
the endpoint and build Grafana dashboards on top for long-term observability, capacity planning, and alerting.
</p>
<pre className="mt-4 overflow-x-auto rounded-lg border border-surface-700/50 bg-surface-950/80 p-4 text-sm"><code>{`# prometheus.yml scrape config
<p>
The metrics endpoint is unauthenticated by default for internal scraping. If your Prometheus instance is on a
different host or network, place it behind the same Tailscale Tailnet or restrict access with a reverse-proxy
basic-auth rule in Caddy.
</p>
<pre className="mt-4 overflow-x-auto rounded-lg border border-surface-700/50 bg-surface-950/80 p-4 text-sm"><code>{`# prometheus.yml — scrape DashCaddy
scrape_configs:
- job_name: 'dashcaddy'
metrics_path: /metrics
static_configs:
- targets: ['dashcaddy-host:3000']`}</code></pre>
<h2>MCP &amp; AI assistants</h2>
- targets: ['dashcaddy-host:3000']
# Optional: increase scrape frequency for faster alerting
scrape_interval: 15s
scrape_timeout: 10s`}</code></pre>
<p>
The built-in <strong>MCP Server</strong> exposes DashCaddy operations to AI assistants and external automation.
Combined with the <strong>AI Intent Router</strong>, you can issue natural-language commands
(&ldquo;restart the media server&rdquo;, &ldquo;deploy the postgres template&rdquo;) and have DashCaddy execute
the real infrastructure action. See the <a href="/docs/api">API and Automation</a> guide for details.
Useful PromQL starters once data is flowing: <code>dashcaddy_service_health == 0</code> (unhealthy services),
<code> rate(dashcaddy_http_requests_total[5m])</code> (request throughput), and
<code>dashcaddy_cert_expiry_days &lt; 14</code> (certificates expiring soon).
</p>
<h2>MCP Server &amp; AI assistants</h2>
<p>
The built-in <strong>MCP (Model Context Protocol) Server</strong> exposes DashCaddy operations to AI assistants
and external automation. Combined with the <strong>AI Intent Router</strong>, you can issue natural-language
commands — &ldquo;restart the media server&rdquo;, &ldquo;deploy the postgres template&rdquo;, &ldquo;is the
database healthy?&rdquo; — and have DashCaddy execute the real infrastructure action through the standard MCP
tool interface.
</p>
<p>
This turns DashCaddy into an AI-operable control plane: the same operations available in the dashboard are
available as MCP tools, so an assistant like Claude or GPT can inspect and manage your infrastructure directly.
Full setup instructions, the tool catalog, and intent examples are in the <a href="/docs/api">API and Automation</a> guide.
</p>
<h2>How the layers fit together</h2>
<ul>
<li><strong>Deploy / Adopt</strong> → Docker runs the container.</li>
<li><strong>Publish</strong> → Caddy creates the reverse-proxy route and TLS cert.</li>
<li><strong>Resolve</strong> → Technitium DNS creates the hostname record.</li>
<li><strong>Trust</strong> → DashCA distributes the root CA for internal HTTPS.</li>
<li><strong>Observe</strong> → health checks + Prometheus + WebSocket live updates.</li>
<li><strong>Secure</strong> → Security Center aggregates events; audit logging records every change.</li>
</ul>
<p>
The table below maps each integration to the layer it provides and the DashCaddy feature that consumes it.
When a service fails, locate the row whose symptom matches, then debug that integration directly.
</p>
<table>
<thead>
<tr>
<th>Layer</th>
<th>Integration</th>
<th>DashCaddy feature that uses it</th>
</tr>
</thead>
<tbody>
<tr>
<td><strong>Runtime</strong></td>
<td>Docker / Docker Compose</td>
<td>Deploy, adopt, lifecycle, templates, service discovery</td>
</tr>
<tr>
<td><strong>Proxy</strong></td>
<td>Caddy (Admin API)</td>
<td>Reverse proxy routes, Caddyfile-as-Code, auto HTTPS</td>
</tr>
<tr>
<td><strong>DNS</strong></td>
<td>Technitium DNS</td>
<td>Automatic A/CNAME record creation &amp; cleanup</td>
</tr>
<tr>
<td><strong>Trust</strong></td>
<td>DashCA (internal CA)</td>
<td>Root certificate distribution for internal HTTPS</td>
</tr>
<tr>
<td><strong>Access</strong></td>
<td>Tailscale</td>
<td>Private networking, Tailnet-only publishing</td>
</tr>
<tr>
<td><strong>Observe</strong></td>
<td>Prometheus / Grafana</td>
<td>Metrics export, alerting, long-term dashboards</td>
</tr>
<tr>
<td><strong>Automate</strong></td>
<td>MCP Server + AI Intent Router</td>
<td>Natural-language ops, AI assistant tool surface</td>
</tr>
<tr>
<td><strong>Secure</strong></td>
<td>Security Center + audit log</td>
<td>Event aggregation, change auditing, RBAC</td>
</tr>
</tbody>
</table>
<h2>Operational flow: deploy to observe</h2>
<p>
When everything is wired correctly, a single service publish triggers the full chain automatically:
</p>
<ol>
<li><strong>Deploy / Adopt</strong> — Docker runs the container (or adopts an existing one).</li>
<li><strong>Publish</strong> — Caddy creates the reverse-proxy route and requests a TLS certificate.</li>
<li><strong>Resolve</strong> — Technitium DNS creates the hostname record so the domain resolves.</li>
<li><strong>Trust</strong> — DashCA distributes the root CA so clients accept the internal cert.</li>
<li><strong>Observe</strong> — health checks, Prometheus metrics, and WebSocket live updates report state.</li>
<li><strong>Secure</strong> — Security Center aggregates events; audit logging records every change.</li>
</ol>
<p>
Each step is independently observable. If a service is unreachable, walk the chain in order — the first broken
step is your failure. For the full diagnostic procedure, see <a href="/docs/troubleshooting">Troubleshooting</a>.
</p>
</DocsLayout>
<Footer />
</div>