dashcaddy/WHAT-IS-DASHCADDY.md

What is DashCaddy?

DashCaddy is a self-hosted web dashboard that unifies Docker container management, Caddy reverse proxy configuration, DNS automation, and SSL certificate provisioning into a single interface. It is designed for homelabbers and self-hosters who want to deploy and manage services without manually editing config files, writing Docker Compose YAML, or configuring DNS records by hand.

You open one page, click "Deploy", pick an app, and DashCaddy handles everything: pulls the Docker image, starts the container, creates a DNS record, adds a reverse proxy block with automatic HTTPS, and registers the service on your dashboard — all in about 30 seconds.

The Stack

Layer	Technology	Role
Frontend	Vanilla JS SPA (~12,000 lines across 33 modules)	Dashboard UI, modals, wizards
Backend	Node.js / Express (~20,000 lines across 22 modules + 20 route files)	API server with 125+ endpoints
Reverse Proxy	Caddy	HTTPS termination, internal CA, automatic certificates
DNS	Technitium DNS Server	Automatic A-record creation for *.sami domains
Containers	Docker (via dockerode)	Application lifecycle management
Auth	TOTP (RFC 6238) + JWT	Two-factor authentication for dashboard access
Encryption	AES-256-GCM	Credential storage with OS keychain fallback

The API server runs inside a Docker container (caddy-api) on port 3001. Caddy sits in front of everything on port 443, terminating TLS with certificates signed by its own root CA.

What It Does

One-Click App Deployment

55 pre-configured templates across 16 categories (Media, Downloads, Productivity, Development, Monitoring, DNS, Security, and more). Each template defines the Docker image, default port, environment variables, volume mounts, health check endpoint, and setup instructions. Deploying an app:

1. Pulls the Docker image
2. Creates the container with the right env vars, ports, and volumes
3. Creates a DNS A-record on Technitium (e.g., plex.sami)
4. Adds a reverse proxy block to the Caddyfile with TLS
5. Reloads Caddy
6. Registers the service on the dashboard with health monitoring

Dashboard

Real-time service cards showing status (up/slow/down), response time, uptime percentage, and container ID. Each card has controls to open the service, restart the container, view logs, edit settings, manage auto-login credentials, or delete the service.

Special top-row cards for DNS servers, internet connectivity, TOTP auth status, and the certificate authority.

Smart Arr Connect

A four-phase wizard that auto-detects Plex, Radarr, Sonarr, Overseerr/Jellyseerr, and Prowlarr, fetches their API keys, and wires them together automatically — connecting Overseerr to Plex, configuring Prowlarr with indexers for Radarr/Sonarr, etc.

Auto-Login SSO

Per-service credential storage that authenticates users into services transparently via Caddy's forward_auth directive. Supports cookie-based auth, JWT-based auth (Open WebUI, Plex), IP-based auth (router), and Emby/Jellyfin token auth with separate device IDs to avoid token invalidation.

DashCA (Certificate Authority Distribution)

A static site at ca.sami that auto-detects the visitor's OS and provides one-click installation of the root CA certificate. Supports Windows (PowerShell), macOS (.mobileconfig), Linux (shell script), iOS (profile), and Android (direct .crt download).

Monitoring and Operations

• Health Checker: Periodic HTTP probes with configurable endpoints per service
• Resource Monitor: Per-container CPU, memory, disk I/O, and network stats
• Update Manager: Checks Docker Hub for newer image versions, one-click updates
• Backup/Restore: Export/import full dashboard configuration as JSON
• Audit Logger: Tracks all administrative actions
• Error Log Viewer: Aggregated error logs with severity filtering
• Metrics: Request counts, response times, error rates, business events (deploys, deletions, DNS records created)
• Notifications: Configurable alerts for health check failures and resource thresholds

Security

• TOTP two-factor authentication with QR code setup
• CSRF token protection on all mutating endpoints
• Helmet security headers
• Rate limiting (general, strict, TOTP tiers)
• Input validation and sanitization (via validator library)
• AES-256-GCM credential encryption with OS keychain integration
• Docker security scanning
• API key management
• Non-root container execution with health checks

Other Features

• Three themes (dark, light, blue)
• Keyboard shortcuts
• Customizable logo with position control
• Weather widget
• Setup wizard with three modes (Simple, Homelab, Public Server)
• Guided onboarding tour (Driver.js)
• Tailscale integration for access control
• Media folder browser for configuring volume mounts
• Interactive API documentation (OpenAPI/Swagger)

---

Architecture Diagram

  Browser (index.html)
      │
      ▼
  Caddy :443  ─── TLS (internal CA) ───┐
      │                                 │
      ├── /api/*  → caddy-api :3001     │
      ├── *.sami  → reverse proxy       │
      │     to Docker containers        │
      └── ca.sami → static DashCA site  │
                                        │
  caddy-api container                   │
      ├── Express (server.js)           │
      │     ├── 20 route modules        │
      │     ├── State Manager (lock)    │
      │     ├── Credential Manager      │
      │     ├── Health Checker          │
      │     ├── Resource Monitor        │
      │     └── Metrics Collector       │
      │                                 │
      ├──→ Docker Engine (dockerode)    │
      ├──→ Caddy Admin API :2019        │
      ├──→ Technitium DNS :5380         │
      └──→ services.json (file-locked)  │

Current State

Version: 0.95 (1.0 = public release)

The project is fully functional and in daily use. All core features work. The codebase has a test suite (17 test files under __tests__/) covering validators, crypto, health checks, state management, API endpoints, and integration scenarios.

---

Obstacles to v1.0 Release

1. Windows-Only — No Cross-Platform Support

DashCaddy was built on and for Windows. The entire deployment model assumes:

• C:/caddy/ as the production path
• Windows-style path handling throughout (C:\caddy\Caddyfile, host.docker.internal)
• Docker Desktop for Windows
• Windows Task Scheduler for backups
• PowerShell for CA certificate installation

A Linux or macOS user cannot run this without significant path rewiring. For a public release, either the documentation must clearly state "Windows only" or the path handling needs to be abstracted with platform-aware defaults.

2. Hardcoded Infrastructure Assumptions

The codebase has assumptions baked in that only apply to the author's setup:

• .sami TLD: The local domain suffix is referenced throughout (Caddyfile templates, DNS record creation, documentation). A public user would need their own TLD — this needs to be a first-run configuration option, not a find-and-replace exercise.
• Technitium DNS: DNS automation assumes Technitium's REST API. Users running Pi-hole, CoreDNS, or no local DNS server have no path. The DNS layer needs to be pluggable or clearly documented as a hard requirement.
• Docker Desktop: Container operations assume Docker Desktop's host.docker.internal hostname. Native Docker on Linux uses localhost differently.
• Caddy internal CA: The TLS model assumes Caddy's built-in PKI. Users wanting Let's Encrypt or other CAs need a different onboarding flow (partially addressed by the "Public Server" setup wizard mode).

3. Single-Page HTML Monolith

The frontend is a ~12,000-line single HTML + 33 JS files architecture with no build step, no bundler, no framework, and no component system. While this means zero build tooling to configure, it creates obstacles:

• No minification or tree-shaking — the full payload is served on every load
• No code splitting — all 33 modules load upfront
• IIFEs communicate through window globals — fragile, hard to test
• No TypeScript — no compile-time safety on a 12k-line frontend
• CSS is embedded in the HTML — no style extraction or scoping

This works fine for a personal tool but makes contribution and maintenance harder at scale.

4. No Automated Test Coverage for the Frontend

The backend has 17 test files with unit and integration tests. The frontend has zero tests. The dashboard UI is the primary interface users interact with, and it has no test safety net — no unit tests, no E2E tests, no screenshot regression tests.

5. No CI/CD Pipeline

There is no GitHub Actions workflow, no pre-commit hooks, no automated linting, and no automated test runs. The deployment process is manual:

1. Edit files in e:/CaddyCerts/sites/dashcaddy-api/
2. Copy JS files to C:/caddy/sites/dashcaddy-api/
3. Run docker restart caddy-api

A public project needs at minimum: automated tests on push, a linter, and a documented release process.

6. No Installation or Setup Documentation

There is no README explaining how to install DashCaddy from scratch. The CLAUDE.md is an internal reference for AI assistants. A new user would need:

• Prerequisites (Docker Desktop, Caddy, Technitium, Node.js)
• Step-by-step installation guide
• First-run configuration walkthrough
• Troubleshooting guide
• Architecture overview

7. Single-User Only

There is no concept of user accounts, roles, or permissions. TOTP protects access but there's one global session. For a household with multiple users, there's no way to give someone read-only access or restrict who can deploy/delete containers.

8. No Container Orchestration Beyond Single-Host

DashCaddy manages containers on one Docker host. There's no support for:

• Docker Compose stacks (multi-container apps like Nextcloud + MariaDB + Redis)
• Docker Swarm or Kubernetes
• Remote Docker hosts
• Container networking (custom networks, inter-container communication)

Apps that need multiple containers (databases, caches, sidecars) must be set up manually.

9. Credential and Secret Management Gaps

While credentials are encrypted with AES-256-GCM, the encryption key management has limitations:

• The master key derivation and storage strategy isn't documented for end users
• Key rotation exists but there's no scheduled rotation or policy
• Backup exports include encrypted credentials but the key management for restoring on a different machine isn't clear
• No integration with external secret managers (Vault, 1Password, etc.)

10. Incomplete Template Coverage

55 templates is a strong start, but several popular self-hosted apps are missing, and the template system has constraints:

• No user-contributed templates or template marketplace
• No template versioning — if an image tag changes, templates need manual updates
• No Docker Compose support — templates are single-container only
• Environment variable templating is basic ({{PORT}}, {{SUBDOMAIN}}) with no conditional logic

11. No Persistent Logging or Metrics Storage

Metrics (request counts, response times, business events) are in-memory only — they reset on container restart. There's no time-series database, no Prometheus endpoint, no Grafana integration. For a monitoring-focused dashboard, losing all metrics on restart is a significant gap.

12. The Development/Production File Split

The two-directory development model (e:/CaddyCerts/sites/ for editing, C:/caddy/ for production) works for the author but would confuse contributors and can't work as-is for other users. A public release needs a single canonical source of truth with a proper build/deploy pipeline.

---

What's Strong

Despite these obstacles, DashCaddy has substantial strengths that position it well for release:

• Feature-complete for its core use case: Deploy apps, manage reverse proxy, automate DNS — it all works
• Security-first design: TOTP, CSRF, rate limiting, encryption, input validation, non-root containers
• Polished UI: Themes, keyboard shortcuts, onboarding tour, skeleton loaders, responsive design
• Smart Arr Connect: A genuinely useful automation that saves significant manual configuration
• Auto-Login SSO: Handles the messy reality of diverse auth mechanisms (cookies, JWT, IP-based, localStorage)
• 55 app templates: Broad coverage of the self-hosting ecosystem
• Thread-safe state management: Proper file locking prevents corruption under concurrent access
• In-memory metrics and monitoring: Even without persistence, the real-time view is useful
• Test suite exists: 17 backend test files covering critical paths
• Modular route architecture: 20 route files keep the 125+ endpoints organized and maintainable

Summary

DashCaddy is a mature, feature-rich self-hosting dashboard that solves a real problem — the tedium of manually configuring Docker + reverse proxy + DNS for every new service. It's daily-driver stable for a single Windows user with Caddy and Technitium DNS.

The gap between "works great for me" and "anyone can install this" is the remaining 0.05 to v1.0. The biggest obstacles are cross-platform support, installation documentation, and removing the hardcoded infrastructure assumptions. The frontend architecture and CI/CD are secondary concerns that matter more for long-term maintainability than for a functional v1.0 release.