+++ Before you begin: Complete the Installation Guide first. You need a running DashCaddy instance with the dashboard accessible, the API responding on
+/healthz, and Caddy's Admin API reachable. Technitium DNS is recommended but optional — services will still deploy without it using direct IP access. +
When you deploy a service, DashCaddy automates the full infrastructure chain:
+ You provide the intent (which app, which hostname), and DashCaddy coordinates every layer atomically. + If any step fails, the operation rolls back cleanly — you never end up with a half-wired service. +
- Already running Docker containers? DashCaddy's Service Discovery scans the host and lists + Already running Docker containers? DashCaddy's Service Discovery scans the host and lists every running container, marking any that are not yet managed.
-- For custom images or apps not in the template library, define the service by hand: -
-- The magic is that the three layers are coordinated as a single transaction rather than three manual steps: -
-- If any layer is not configured (for example, no DNS integration), DashCaddy simply skips that step and - the service still deploys with whatever layers are available. + For custom images or apps not in the template library, define the service by hand with full control + over image, ports, volumes, and environment variables.
-- For services that should stay on the local network, verify three things: + Let's walk through deploying Plex Media Server using the template library. This is the most common + path for new users and demonstrates the full deployment chain.
+ ++ From the dashboard sidebar, click New Service → From Template. The template library + opens with a searchable grid of 76+ applications. +
+ ++ Type "Plex" in the search bar, or browse the "Media" category. Click the Plex template card to + open its configuration form. +
+ +The form is pre-filled with sensible defaults. Review and adjust:
plex (used for internal identification)plex.local (the subdomain DashCaddy will publish)linuxserver/plex:latest32400 (Plex's default web interface port)/opt/plex/config:/config and /mnt/media:/mediaPUID=1000, PGID=1000, VERSION=docker- Debug in order, layer by layer: backend container, backend port reachability, reverse-proxy route, DNS - resolution, TLS trust, then dashboard/API state. See the Troubleshooting - guide for the full checklist. + Click Deploy. DashCaddy now executes the full deployment chain:
+linuxserver/plex:latest Docker imageplex.local → localhost:32400plex.local via DashCAplex.local to your host IP+ Within 30 seconds, the service card on the dashboard should show Healthy with a green + status indicator. Click the service to see its detail page, which shows: +
++ If you already have Docker containers running that you want DashCaddy to manage, use Service Discovery + instead of redeploying from scratch. +
+ ++ Service Discovery scans the Docker socket and lists every running container on the host. Containers + that are already managed by DashCaddy are marked as "Managed." Unmanaged containers are listed with + their image name, exposed ports, and current status. +
+ +grafana.local)+ DashCaddy creates a service record, generates the Caddy route, DNS record, and certificate — without + restarting or modifying the running container. The container continues running with its existing + configuration; DashCaddy simply adds the proxy and DNS layers on top. +
+ ++ Understanding what happens during a deployment helps you troubleshoot when things go wrong. Here's + the full chain, layer by layer: +
+ +
+ The orchestration layer calls the Docker API to create a container from the specified image. It attaches
+ the container to the dashcaddy-net bridge network, mounts the configured volumes, and injects
+ environment variables. The container starts in the background and begins listening on its configured port.
+
+ A service record is written to the DashCaddy state store (a SQLite database in ./data/services.db).
+ The record includes the service name, hostname, backend port, container ID, deployment timestamp, and
+ configuration metadata. This record is the source of truth for the dashboard and API.
+
+ The Caddyfile-as-Code builder generates a route configuration: +
+{`plex.local {
+ reverse_proxy localhost:32400
+ encode gzip
+ header / {
+ Strict-Transport-Security "max-age=31536000;"
+ }
+}`}
+ This configuration is applied atomically through the Caddy Admin API (POST /load). Caddy
+ reloads its configuration without downtime and begins routing traffic for plex.local to
+ localhost:32400.
+
+ If Technitium DNS is configured, the orchestration layer calls the Technitium API to create an A record: +
+{`POST /api/zones/records/create
+{
+ "zone": "local",
+ "type": "A",
+ "name": "plex",
+ "ipAddress": "192.168.1.100"
+}`}
+ The DNS record propagates immediately (Technitium is authoritative for the local zone).
+ Clients on your network can now resolve plex.local to your host's IP address.
+
+ Caddy's built-in ACME client detects the new hostname and requests a certificate. For internal domains
+ like plex.local, Caddy uses its internal CA (DashCA) rather than Let's Encrypt. The certificate
+ is issued, stored in Caddy's data directory, and served automatically for all HTTPS connections to
+ plex.local.
+
+ The certificate is valid for 90 days and renewed automatically 30 days before expiration. DashCaddy + tracks certificate expiration dates and surfaces warnings on the dashboard when renewal is approaching. +
+ ++ Once the service is deployed, DashCaddy starts a health check loop that runs every 30 seconds. The health + check performs an HTTP GET to the backend port and expects a 2xx or 3xx response. If the check fails three + times in a row, the service is marked Unhealthy on the dashboard and an event is logged. +
++ Health status updates are pushed to the dashboard over WebSocket, so you see status changes in real-time + without refreshing the page. +
+ ++ When deploying a service, these are the configuration fields available in the deployment form: +
+| Field | +Required | +Description | +
|---|---|---|
| Service Name | +Yes | +Internal identifier (lowercase, no spaces) | +
| Hostname | +Yes | +Subdomain for the service (e.g., plex.local) | +
| Container Image | +Yes | +Docker image (e.g., linuxserver/plex:latest) | +
| Backend Port | +Yes | +Port the container listens on internally | +
| Volumes | +No | +Host:container path mappings for persistent storage | +
| Environment Variables | +No | +Key-value pairs injected into the container | +
| Network | +No | +Docker network to attach (default: dashcaddy-net) | +
| Restart Policy | +No | +Container restart behavior (default: unless-stopped) | +
| Health Check Path | +No | +HTTP path for health checks (default: /) | +
+ For services that should stay on the local network (not exposed to the internet), use a .local
+ or .internal TLD. Ensure client devices trust the DashCA root certificate (download it from
+ the DashCA page in the dashboard). The service will be accessible at https://servicename.local
+ with a trusted HTTPS connection, but only from devices on your network that have the root cert installed.
+
+ When deploying manually or editing a template, you can add custom environment variables in the deployment + form. Each variable is a key-value pair that gets injected into the container at startup. Common examples: +
+PUID=1000 / PGID=1000 — user/group ID for file permissions (LinuxServer images)TZ=America/New_York — timezone for log timestampsDB_PASSWORD=secret — database credentials for apps like Nextcloud
+ DashCaddy handles multiple services on the same host automatically. Each service gets a unique subdomain,
+ and Caddy routes traffic based on the Host header. You can run Plex on plex.local,
+ Nextcloud on nextcloud.local, and Grafana on grafana.local — all on the same
+ host, all on port 443, with no port conflicts.
+
+ If you have a container running outside of DashCaddy (e.g., started manually with docker run),
+ use Service Discovery to adopt it. DashCaddy will add the proxy and DNS layers without restarting the
+ container. The container's existing volumes, environment, and network configuration are preserved.
+
After deploying a service, verify each layer:
+curl http://localhost:32400 returns a response from the
+ application
+ curl http://localhost:2019/config/ shows a route for your
+ hostname
+ ping plex.local resolves to your host's IP address
+ curl -v https://plex.local shows a valid certificate
+ (no warnings if DashCA root is installed)
+ If the service does not come up correctly, debug in order, layer by layer:
+docker logs <container_name> for startup errors+ See the Troubleshooting Guide for + the full checklist and common error patterns. +
+ +Before installing, make sure the host has the following:
-Before installing DashCaddy, verify that your host meets these minimum requirements:
+| Component | +Minimum | +Recommended | +
|---|---|---|
| Operating System | +Linux (Ubuntu 20.04+, Debian 11+, CentOS 8+) | +Ubuntu 22.04 LTS or Debian 12 | +
| CPU | +2 cores | +4+ cores | +
| RAM | +2 GB | +4+ GB (8 GB for 20+ services) | +
| Disk | +10 GB free | +50+ GB SSD | +
| Docker | +20.10+ | +Latest stable | +
| Docker Compose | +v2.0+ | +Latest stable | +
| Node.js | +20.x LTS | +20.x LTS or 22.x LTS | +
| Caddy | +2.6+ with Admin API | +Latest stable | +
| Technitium DNS | +Optional | +Latest stable (for auto DNS) | +
++ Note: DashCaddy can run on Windows and macOS for development, but production deployments should target Linux. Docker Desktop works for testing but is not recommended for production workloads. +
+
The fastest path to a running DashCaddy is the bundled start.sh script. It performs environment
- checks, pulls the required containers, generates configuration, and brings the stack up.
+ checks, pulls the required containers, generates configuration, and brings the stack up in a single command.
{`# Clone the repository
-git clone https://github.com/samiahmed7777/dashcaddy.git
-cd dashcaddy
-# Make the launcher executable and run it
-chmod +x start.sh
-./start.sh`}{`git clone https://github.com/samiahmed7777/dashcaddy.git
+cd dashcaddy`}{`chmod +x start.sh`}{`./start.sh`}
The script is idempotent — re-running it will reconcile the stack rather than clobber an existing install.
+ If DashCaddy is already running, start.sh detects this and offers to update configuration or
+ restart services instead of reinstalling from scratch.
- For users who prefer a walk-through, DashCaddy includes a dedicated installer that steps through: -
+Under the hood, the script performs these steps:
.env file with sensible defaults/healthz
- On first launch the dashboard opens to the Smart Defaults Wizard. It surveys your host and
- pre-fills sensible choices so you can go from install to a working deployment in minutes:
+ If you prefer to inspect or customize the Docker Compose configuration before launching, here's the
+ default docker-compose.yml that start.sh generates:
{`version: '3.8'
+
+services:
+ dashcaddy-api:
+ image: samiahmed7777/dashcaddy-api:latest
+ container_name: dashcaddy-api
+ restart: unless-stopped
+ ports:
+ - "3001:3001" # API port
+ volumes:
+ - ./data:/app/data
+ - ./config:/app/config
+ - /var/run/docker.sock:/var/run/docker.sock:ro
+ environment:
+ - NODE_ENV=production
+ - DASHCADDY_PORT=3001
+ - CADDY_ADMIN_URL=http://caddy:2019
+ - TECHNITIUM_API_URL=http://technitium:5380
+ - TECHNITIUM_API_TOKEN=\${TECHNITIUM_API_TOKEN}
+ - JWT_SECRET=\${JWT_SECRET}
+ - DASHCA_ENABLED=true
+ depends_on:
+ - caddy
+ - technitium
+ networks:
+ - dashcaddy-net
+
+ dashcaddy-dashboard:
+ image: samiahmed7777/dashcaddy-dashboard:latest
+ container_name: dashcaddy-dashboard
+ restart: unless-stopped
+ ports:
+ - "3000:3000" # Dashboard port
+ environment:
+ - NEXT_PUBLIC_API_URL=http://localhost:3001
+ depends_on:
+ - dashcaddy-api
+ networks:
+ - dashcaddy-net
+
+ caddy:
+ image: caddy:2-alpine
+ container_name: caddy
+ restart: unless-stopped
+ ports:
+ - "80:80"
+ - "443:443"
+ - "2019:2019" # Admin API
+ volumes:
+ - ./caddy/Caddyfile:/etc/caddy/Caddyfile
+ - ./caddy/data:/data
+ - ./caddy/config:/config
+ networks:
+ - dashcaddy-net
+
+ technitium:
+ image: technitium/dns-server:latest
+ container_name: technitium
+ restart: unless-stopped
+ ports:
+ - "5380:5380" # Web console
+ - "53:53/udp"
+ - "53:53/tcp"
+ volumes:
+ - ./technitium:/etc/dns
+ environment:
+ - DNS_SERVER_DOMAIN=local
+ networks:
+ - dashcaddy-net
+
+networks:
+ dashcaddy-net:
+ driver: bridge`}
+ DashCaddy's behavior is controlled through environment variables in the .env file. Here's
+ a complete reference:
+
| Variable | +Default | +Description | +
|---|---|---|
| NODE_ENV | +production | +Runtime environment (development or production) | +
| DASHCADDY_PORT | +3001 | +Port for the DashCaddy API server | +
| CADDY_ADMIN_URL | +http://caddy:2019 | +Caddy Admin API endpoint | +
| TECHNITIUM_API_URL | +http://technitium:5380 | +Technitium DNS API endpoint | +
| TECHNITIUM_API_TOKEN | +(required) | +API token for Technitium DNS authentication | +
| JWT_SECRET | +(auto-generated) | +Secret key for JWT token signing | +
| DASHCA_ENABLED | +true | +Enable internal certificate authority | +
| BASE_DOMAIN | +local | +Base domain for service hostnames | +
| PROMETHEUS_ENABLED | +true | +Expose Prometheus metrics at /metrics | +
| LOG_LEVEL | +info | +Logging verbosity (debug, info, warn, error) | +
| DATA_DIR | +./data | +Path for persistent state storage | +
++ ++ Smart Defaults Wizard: On first launch, the dashboard opens to the Smart Defaults Wizard. It surveys your host and pre-fills sensible choices so you can go from install to a working deployment in minutes. Every default is editable — the wizard simply gives you a known-good starting point instead of a blank slate. +
+
The wizard performs these tasks automatically:
- Every default is editable — the wizard simply gives you a known-good starting point instead of a blank slate. -
- If you want direct control over paths, services, Caddy, and DNS integration, you can deploy manually:
+ If you want direct control over paths, services, Caddy, and DNS integration, you can deploy manually
+ instead of using start.sh:
npm ci).npm run start or via your process manager).git clone https://github.com/samiahmed7777/dashcaddy.gitcd dashcaddy && npm ci.env.example to .env and configure environment variablesnpm run start (or use your process manager like systemd or PM2)After the stack is up, verify each layer:
-/healthz and /readyz./metrics (if scraping is enabled).If you encounter problems during installation, check this troubleshooting table:
+| Symptom | +Cause | +Solution | +
|---|---|---|
| Port 80 or 443 already in use | +Another web server (nginx, Apache) is running | +Stop the conflicting service or change Caddy's ports in docker-compose.yml | +
| Docker permission denied | +Current user not in docker group | +Run sudo usermod -aG docker $USER and log out/in |
+
| Caddy Admin API unreachable | +Caddy not running or Admin API disabled | +Ensure Caddy is running with admin :2019 in its config |
+
| Technitium API token invalid | +Token not set or expired | +Generate a new token in Technitium web console and update .env | +
| Dashboard shows 502 Bad Gateway | +API server not responding | +Check docker logs dashcaddy-api for errors |
+
| Out of memory during deployment | +Insufficient RAM for container workloads | +Increase host RAM or reduce concurrent service deployments | +
| Certificate trust errors in browser | +DashCA root cert not installed on client | +Download root cert from DashCA page and install on client device | +
After the stack is up, verify each layer with these commands:
+ +{`docker ps --filter "name=dashcaddy"
+# Expected: dashcaddy-api, dashcaddy-dashboard, caddy, technitium all running`}{`curl http://localhost:3001/healthz
+# Expected: {"status":"ok","version":"1.0.0"}
+
+curl http://localhost:3001/readyz
+# Expected: {"status":"ready","checks":{"caddy":true,"technitium":true}}`}{`curl http://localhost:2019/config/
+# Expected: JSON configuration object`}{`curl http://localhost:5380/api/dns/zones/list?token=YOUR_TOKEN
+# Expected: List of DNS zones`}{`curl http://localhost:3001/metrics
+# Expected: Prometheus-formatted metrics output`}Open your browser and navigate to http://localhost:3000 (or your configured domain). You should see the DashCaddy dashboard login screen.
- Once install checks pass, head to the Deploy Your First Service guide to + Once install checks pass, head to the Deploy Your First Service guide to bring your first application online.
++ If you need to understand the architecture in more depth, see the Product Overview. +
diff --git a/src/app/docs/integrations/page.tsx b/src/app/docs/integrations/page.tsx index 6e92cab..1e997ed 100644 --- a/src/app/docs/integrations/page.tsx +++ b/src/app/docs/integrations/page.tsx @@ -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." > -- 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. +
++ 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.
-
- Caddy is the reverse proxy and automatic HTTPS layer. DashCaddy communicates with the Caddy Admin API
- to create, update, and remove routes, and to trigger certificate issuance. Caddy'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 (/var/run/docker.sock) to start, stop, restart, inspect, and adopt containers, and to
+ deploy the 76+ 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 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.
Instead of hand-editing Caddyfiles, DashCaddy exposes a visual Caddyfile-as-Code builder. 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.
++ 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
- Technitium DNS
+ 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 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.
++ 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 is the certificate distribution system that makes internal HTTPS practical. Caddy'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 .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.
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 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.
+
+ 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
- Prometheus & Grafana — metrics
+# 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. +
DashCaddy exports metrics in Prometheus format at /metrics, 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.
{`# prometheus.yml scrape config
+
+ 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']`}
-
- MCP & AI assistants
+ - targets: ['dashcaddy-host:3000']
+ # Optional: increase scrape frequency for faster alerting
+ scrape_interval: 15s
+ scrape_timeout: 10s`}
- The built-in MCP 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”) and have DashCaddy execute
- the real infrastructure action. See the API and Automation guide for details.
+ Useful PromQL starters once data is flowing: dashcaddy_service_health == 0 (unhealthy services),
+ rate(dashcaddy_http_requests_total[5m]) (request throughput), and
+ dashcaddy_cert_expiry_days < 14 (certificates expiring soon).
+
+ 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.
+ 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. +
+| Layer | +Integration | +DashCaddy feature that uses it | +
|---|---|---|
| Runtime | +Docker / Docker Compose | +Deploy, adopt, lifecycle, templates, service discovery | +
| Proxy | +Caddy (Admin API) | +Reverse proxy routes, Caddyfile-as-Code, auto HTTPS | +
| DNS | +Technitium DNS | +Automatic A/CNAME record creation & cleanup | +
| Trust | +DashCA (internal CA) | +Root certificate distribution for internal HTTPS | +
| Access | +Tailscale | +Private networking, Tailnet-only publishing | +
| Observe | +Prometheus / Grafana | +Metrics export, alerting, long-term dashboards | +
| Automate | +MCP Server + AI Intent Router | +Natural-language ops, AI assistant tool surface | +
| Secure | +Security Center + audit log | +Event aggregation, change auditing, RBAC | +
+ When everything is wired correctly, a single service publish triggers the full chain automatically: +
++ 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. +
diff --git a/src/app/docs/overview/page.tsx b/src/app/docs/overview/page.tsx index eb283e7..7892e4c 100644 --- a/src/app/docs/overview/page.tsx +++ b/src/app/docs/overview/page.tsx @@ -10,6 +10,13 @@ export default function DocsOverviewPage() { title="Product Overview" intro="DashCaddy is a self-hosted control plane for deploying, exposing, and managing Docker applications — with automatic DNS, reverse proxy, internal HTTPS, real-time monitoring, AI-driven operations, and centralized fleet visibility." > ++++ What you'll learn: This page covers the full DashCaddy architecture, design philosophy, component breakdown, and how it compares to manual self-hosting. By the end, you'll understand why DashCaddy exists, what problems it solves, and how its layers work together as a unified platform. +
+
DashCaddy brings together the layers that self-hosters usually wire by hand — Docker deployment, @@ -25,59 +32,253 @@ export default function DocsOverviewPage() {
- DashCaddy is a production-grade platform built on a layered stack: + DashCaddy is a production-grade platform built on eight distinct layers, each responsible for a + specific concern. Together they form a complete self-hosting stack that replaces dozens of manual + configuration steps with a single declarative action.
-/api/v1/ for deployments, DNS, reverse proxy, certificates, monitoring, and operational tooling.
- DashCaddy is proprietary software and intellectual property of samiahmed7777. Public-facing
- documentation and branding reflect that commercial/proprietary positioning rather than an open-source default.
- The core platform is fully useful without a license; Premium unlocks a focused set of advanced orchestration features.
+ The Application Layer is what operators interact with directly. It is a React-based dashboard that
+ provides real-time visibility into every service, container, and infrastructure component managed by
+ DashCaddy. Beyond the visual interface, this layer exposes a REST API under /api/v1/ and
+ a WebSocket channel for live updates. Every action available in the UI — deploying a service, editing
+ a Caddy route, reviewing audit logs — is available through the API, making the dashboard a thin client
+ over a fully programmable control plane. The application layer also handles authentication, role-based
+ access control, TOTP two-factor enrollment, and multi-user admin invitations.
+ The Orchestration Layer is the Node.js/Express engine at the heart of DashCaddy. It receives deployment + requests, coordinates Docker container lifecycle, drives Caddy reverse proxy configuration through the + Admin API, manages Technitium DNS records programmatically, and handles certificate issuance and renewal. + This layer is responsible for ensuring that every deployment is atomic — either all layers succeed or the + operation rolls back cleanly. It maintains the authoritative service state store, tracks health checks, + and publishes events over WebSocket for the dashboard. The orchestration engine also powers the Smart + Defaults Wizard, Service Discovery, and the Caddyfile-as-Code builder. +
+ ++ The Runtime Layer is Docker and Docker Compose — the container workloads that actually run your services. + DashCaddy manages container creation, network attachment, volume mounts, environment variable injection, + and lifecycle operations (start, stop, restart, remove). For advanced deployments, the platform supports + Docker Swarm for multi-host orchestration and Fleet Management for coordinating services across multiple + servers. Every container managed by DashCaddy is tracked in the service state store, enabling features + like Service Discovery (adopting existing containers) and Disaster Recovery (full-system backup and restore + with SHA-256 checksum verification). +
+ ++ The Edge Layer is Caddy — the reverse proxy that terminates HTTPS connections and routes traffic to your + services. DashCaddy manages Caddy entirely through its Admin API, never requiring manual edits to a + Caddyfile. The Caddyfile-as-Code builder generates configuration declaratively, and the orchestration + layer applies changes atomically. Caddy handles automatic TLS certificate issuance and renewal using its + built-in ACME client for public domains or its internal CA for private networks. The Edge Layer also + provides load balancing, header manipulation, request logging, and rate limiting — all configurable + through the DashCaddy dashboard without touching Caddy's native configuration syntax. +
+ +
+ The Name Resolution Layer is Technitium DNS — a self-hosted authoritative DNS server that DashCaddy
+ controls programmatically. When you deploy a service with hostname plex.local, the
+ orchestration layer creates an A record pointing to your host's IP address automatically. When you
+ remove the service, the record is cleaned up. This eliminates the manual DNS management that plagues
+ most self-hosting setups. Technitium DNS also supports zone transfers, forwarding, and custom record
+ types for advanced networking scenarios. The integration is optional — if you don't configure DNS,
+ DashCaddy skips this layer and your services still deploy with direct IP access.
+
+ The Trust Layer handles certificate authority management and internal HTTPS distribution. Caddy's built-in + CA issues certificates automatically for every service, but those certificates are only trusted if the + client device trusts the issuing CA. DashCaddy solves this with DashCA — an internal certificate authority + distribution surface. The Smart Defaults Wizard initializes DashCA on first launch and offers the root + certificate for download. Once installed on client devices (browsers, phones, IoT devices), every service + managed by DashCaddy presents a trusted HTTPS connection without certificate warnings. This layer also + handles certificate renewal tracking and expiration alerts. +
+ +
+ The Observability Layer provides real-time health monitoring, structured audit logging, and metrics export.
+ Every service managed by DashCaddy has a health check that runs continuously, with status updates pushed
+ to the dashboard over WebSocket. The layer exports Prometheus-compatible metrics at /metrics,
+ enabling integration with Grafana, VictoriaMetrics, or any Prometheus-compatible monitoring stack. Audit
+ logs capture every administrative action — who deployed what, when, and from which IP — providing the
+ accountability required for multi-user environments. The Security Center aggregates logs from multiple
+ sources (Caddy access logs, container stdout, authentication events) into a unified event pipeline for
+ threat detection and forensic analysis.
+
+ The Intelligence Layer makes DashCaddy AI-native. The AI Intent Router accepts natural-language commands + like "deploy Plex on port 32400" or "show me all unhealthy services" and translates them into API calls. + The MCP (Model Context Protocol) Server exposes DashCaddy operations to external AI assistants — Claude, + ChatGPT, or any MCP-compatible client can deploy services, check health, or modify configuration through + the protocol. This layer also powers the Plugin system, allowing third-party extensions to hook into + DashCaddy's event stream and extend functionality without modifying core code. +
+ ++ DashCaddy is built on three principles that guide every architectural decision: +
+| Capability | +Manual Setup | +DashCaddy Free | +DashCaddy Premium | +
|---|---|---|---|
| Docker deployment | +Manual compose files | +76+ one-click templates | +Templates + Recipes | +
| Reverse proxy | +Hand-edit Caddyfile | +Caddyfile-as-Code builder | +Same + fleet-wide routes | +
| DNS automation | +Manual record creation | +Technitium integration | +Same + multi-zone | +
| TLS certificates | +Let's Encrypt / manual | +Automatic via Caddy + DashCA | +Same | +
| Monitoring | +Custom scripts | +Real-time health + Prometheus | +Same + fleet dashboard | +
| Multi-user access | +None | +TOTP 2FA + RBAC | +SSO (OIDC/SAML) | +
| Backup & recovery | +Manual snapshots | +One-click backup/restore | +Same + scheduled | +
| AI operations | +None | +Intent Router + MCP Server | +Same | +
| Multi-host orchestration | +Manual Swarm/K8s | +Single host | +Swarm + Fleet Management | +
| Pricing | +Time + complexity | +Free forever | +$20–$99 one-time | +
+ You run Plex, Nextcloud, Home Assistant, and a dozen other services on a single NUC. With DashCaddy,
+ you deploy each from a template, and every service gets a clean subdomain (plex.local,
+ nextcloud.local) with trusted HTTPS. Service Discovery adopts containers you already
+ had running, so you don't need to redeploy anything. The dashboard gives you one place to see health,
+ restart services, and review logs.
+
+ Your team needs Gitea, Grafana, and a wiki behind HTTPS with role-based access. DashCaddy Free handles + deployment, DNS, and certificates. TOTP 2FA and multi-user admin ensure only authorized team members + can modify infrastructure. Audit logs track who deployed what and when. +
+ ++ You manage DashCaddy instances across three offices. Premium's Fleet Management gives you a single + dashboard to monitor all hosts, deploy services to specific sites, and enforce configuration standards. + Swarm support lets you scale a service across multiple nodes within a site. +
+ ++ DashCaddy Premium is a one-time purchase (not a subscription) that unlocks advanced orchestration + features. Pricing tiers: +
++ Premium features include SSO (OIDC/SAML), Recipes (multi-service deployment blueprints), Docker Swarm + orchestration, and Fleet Management for multi-host coordination. The core platform is fully functional + without a license; Premium is for teams that need enterprise-grade access control and multi-site + visibility. +
+ +Self-hosted Docker dashboard with automatic SSL, DNS, and reverse proxy. Making self-hosting beautiful and effortless. diff --git a/src/components/Navbar.tsx b/src/components/Navbar.tsx index 2efb018..b71db84 100644 --- a/src/components/Navbar.tsx +++ b/src/components/Navbar.tsx @@ -19,9 +19,8 @@ export default function Navbar() {