Infrastructure Integrations

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.

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 Troubleshooting guide.

Docker — container runtime

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 (/var/run/docker.sock) to start, stop, restart, inspect, and adopt containers, and to deploy the 77 one-click application templates from the catalog.

The daemon connection is established at startup. If the socket is missing or permissioned for a different user, DashCaddy's /readyz probe will fail immediately — a fast signal that the runtime layer is broken. During the Smart Defaults Wizard, DashCaddy probes the socket, reports the Docker version, and suggests socket paths if the default is not found.

Optional Docker Swarm 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 Premium Features.

# 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

Note: 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.

Caddy — reverse proxy & automatic HTTPS

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 Caddy Admin API (default localhost:2019) to create, update, and remove routes, and to trigger certificate issuance on demand.

Caddy's built-in internal CA auto-generates and renews certificates for every published service. For public domains, Caddy can also use ACME (Let'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.

Caddyfile-as-Code

Instead of hand-editing Caddyfiles, DashCaddy exposes a visual Caddyfile-as-Code builder. You 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.

The generated config is rendered in the service's Caddyfile-as-Code view, 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.

# Example generated Caddyfile (internal CA, lab hostname)
media.lab {
  tls internal

  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
  }
}

Technitium DNS — DNS automation

Technitium DNS is the DNS automation target for record creation and removal. When you deploy or adopt a service, 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.

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 Settings → DNS. 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.

Internal zones (e.g. .lab) 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 Tailscale with a MagicDNS / split-DNS setup.

# 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

DashCA — internal certificate authority

DashCA is the certificate distribution system that makes internal HTTPS practical. Caddy's internal CA issues certificates automatically for .lab 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.

The root certificate must be installed on each client device 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 update-ca-certificates, and mobile profiles) to make this straightforward.

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.

Tailscale — private access

DashCaddy fits naturally into private access patterns with Tailscale. Services can be published only on a Tailnet, keeping them off the public internet while still benefiting from DashCaddy's DNS, proxy, and TLS automation. This is ideal for home labs, internal team tools, and any service that should never be internet-facing.

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 .lab zones for Tailnet clients, while public domains resolve normally.

# 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

# 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

Tip: If you publish services only on the Tailnet, set Caddy to bind to the Tailscale interface IP rather than 0.0.0.0. This guarantees the service is unreachable from the LAN even if the firewall is misconfigured.

Prometheus & Grafana — metrics & observability

DashCaddy exports metrics in Prometheus format at /metrics, including service health, container 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.

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.

# prometheus.yml — scrape DashCaddy
scrape_configs:
  - job_name: 'dashcaddy'
    metrics_path: /metrics
    static_configs:
      - targets: ['dashcaddy-host:3000']
    # Optional: increase scrape frequency for faster alerting
    scrape_interval: 15s
    scrape_timeout: 10s

Useful PromQL starters once data is flowing: dashcaddy_service_health == 0 (unhealthy services), rate(dashcaddy_http_requests_total[5m]) (request throughput), anddashcaddy_cert_expiry_days < 14 (certificates expiring soon).

MCP Server & AI assistants

The built-in MCP (Model Context Protocol) Server exposes DashCaddy operations to AI assistants and external automation. Combined with the AI Intent Router, you can issue natural-language commands — “restart the media server”, “deploy the postgres template”, “is the database healthy?” — and have DashCaddy execute the real infrastructure action through the standard MCP tool interface.

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 API and Automation guide.

How the layers fit together

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.

Operational flow: deploy to observe

When everything is wired correctly, a single service publish triggers the full chain automatically:

1. Deploy / Adopt — Docker runs the container (or adopts an existing one).
2. Publish — Caddy creates the reverse-proxy route and requests a TLS certificate.
3. Resolve — Technitium DNS creates the hostname record so the domain resolves.
4. Trust — DashCA distributes the root CA so clients accept the internal cert.
5. Observe — health checks, Prometheus metrics, and WebSocket live updates report state.
6. Secure — Security Center aggregates events; audit logging records every change.

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 Troubleshooting.