DashCaddy

Self-hosted dashboard for managing Docker apps with automatic SSL, DNS, and reverse proxy configuration.

What is DashCaddy?

DashCaddy is an all-in-one solution for self-hosting Docker applications. It combines:

• 🎨 Beautiful Dashboard - Monitor all your services in one place
• 🐳 Docker Management - Deploy 78 pre-configured apps with one click
• 🔒 Automatic SSL - Internal CA with automatic certificate generation
• 🌐 DNS Integration - Automatic DNS record creation (Technitium DNS)
• 🔄 Reverse Proxy - Caddy configuration managed automatically
• 🔐 Tailscale Support - Secure remote access built-in

Features

Authentication & Security

• Built-in TOTP two-factor authentication
• Fine-grained access control per service
• Secure session management
• Group-based permissions

Dashboard

• Real-time service health monitoring
• Response time tracking
• Status indicators with visual feedback
• Weather widget
• Multiple themes (dark/light/blue)
• Import/export configuration

App Deployment

• 78 pre-configured app templates
• One-click deployment
• Automatic DNS + SSL + reverse proxy setup
• Container health checking
• Deployment status tracking
• SSL certificate generation monitoring

Service Management

• Add/edit/delete services
• Restart containers
• View logs
• Update configurations
• Silent deletions (no annoying popups)

Developer Tools

• Error log viewer
• API endpoints for automation
• Import/export for testing
• Comprehensive error logging

Quick Start

Prerequisites

• Docker & Docker Compose
• Caddy web server
• Technitium DNS (optional, for automatic DNS)
• Node.js 18+ (for API server)

Installation

1. Clone the repository

git clone https://github.com/sami7777/dashcaddy.git
cd dashcaddy

2. Install dependencies

cd dashcaddy-api
npm install

3. Configure environment

cp .env.example .env
# Edit .env with your settings

4. Start the API server

npm start

5. Configure Caddy Add to your Caddyfile:

status.yourdomain.com {
    root * /path/to/dashcaddy/status
    file_server
    reverse_proxy /api/* localhost:3001
}

6. Access the dashboard Open https://status.yourdomain.com in your browser

Health Probes

DashCaddy exposes Kubernetes/Docker-standard health endpoints for container orchestration. No auth required — these are designed for orchestration tooling to poll.

Path	Purpose	Returns
/healthz or /health/live	Liveness — is the Node.js process alive?	200 with {status: "alive", uptime: <seconds>}
/readyz or /health/ready	Readiness — are critical deps reachable? (config file, services file, Docker daemon, Caddy admin API)	200 if all OK, 503 if any dep fails (with details in the checks object)
/health	Backwards-compat alias for /healthz	Same as /healthz

When to use which:

• Use /healthz / /health/live in a livenessProbe — should the container be restarted?
• Use /readyz / /health/ready in a readinessProbe — should traffic be routed to this instance?

Docker Compose healthcheck

Copy-paste this into your DashCaddy docker-compose.yml:

services:
  dashcaddy-api:
    image: ghcr.io/samiahmed7777/dashcaddy-api:latest
    # ... your existing config ...
    healthcheck:
      test: ["CMD", "node", "-e", "require('http').get('http://localhost:3001/readyz', r => process.exit(r.statusCode === 200 ? 0 : 1)).on('error', () => process.exit(1))"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 30s

Kubernetes probes

livenessProbe:
  httpGet:
    path: /healthz
    port: 3001
  initialDelaySeconds: 30
  periodSeconds: 30
readinessProbe:
  httpGet:
    path: /readyz
    port: 3001
  initialDelaySeconds: 10
  periodSeconds: 10

Both endpoints return JSON. Liveness is cheap (no I/O, no deps). Readiness touches the Docker daemon and Caddy admin API with a 3-second timeout each, so it's safe to poll every 10s without load concerns.

Configuration

Environment Variables

Create a .env file in the dashcaddy-api directory:

# Caddy Configuration
CADDYFILE_PATH=/path/to/Caddyfile
CADDY_ADMIN_URL=http://localhost:2019

# DNS Configuration (optional)
DNS_SERVER=192.168.1.1
DNS_TOKEN=your-dns-token

# File Paths
SERVICES_FILE=/path/to/services.json
ERROR_LOG_FILE=/path/to/dashcaddy-errors.log

DNS Integration

DashCaddy works with Technitium DNS for automatic DNS record creation:

1. Install Technitium DNS
2. Create an API token with DNS management permissions
3. Configure DNS credentials in dashboard (🔑 Tokens button)

Tailscale Integration

For secure remote access:

1. Install Tailscale on your server
2. Services can be restricted to Tailscale-only access
3. Configure in deployment settings

Usage

Deploying an App

1. Click "App Selector" button
2. Choose an app from the template library
3. Configure:
   • Subdomain (e.g., jellyfin → jellyfin.yourdomain.com)
   • Port (auto-suggested)
   • IP address (defaults to localhost)
   • Tailscale-only access (optional)
4. Click "Deploy"
5. Wait for SSL certificate generation (30-60 seconds)
6. Access your app!

Managing Services

• View Status: Cards show real-time health and response times
• Open Service: Click "Open" button
• Restart: Click restart button (for Docker containers)
• Delete: Click delete button (removes everything: container, DNS, Caddy config)
• Edit: Click settings button to modify configuration

Viewing Error Logs

1. Click "📋 Logs" button in toolbar
2. View all errors with timestamps and context
3. Refresh to see latest errors
4. Clear logs when resolved

Log PII Redaction

Every log sink (console JSON, error.log, audit details) masks email addresses with a canonical form (sa****@example.com) — raw addresses never reach disk or stdout. When error.log crosses 5 MB it rotates to error.log.1, and the archive is scrubbed with the same canonical mask on rotation.

For pre-existing log files written before this defense existed:

node scripts/redact-log-pii.js --dry-run <file-or-dir>   # see what would change
node scripts/redact-log-pii.js <file-or-dir>             # atomic in-place rewrite

The script is idempotent, never touches byte-identical files (mtime preserved), reuses the same masking code the live logger uses (no regex drift), and post-verifies that no raw address remains (exit code 2 if any does). See dashcaddy-api/scripts/redact-log-pii.js header for flags including --keep-raw (explicitly preserves the raw copy — avoid unless required).

Backup & Restore

Export Configuration:

1. Click "📤 Export" button
2. JSON file downloads with all your services
3. Save safely

Import Configuration:

1. Click "📥 Import" button
2. Select your backup JSON file
3. Confirm import
4. Dashboard reloads with restored configuration

Note: API tokens are not exported for security. Reconfigure after import.

App Templates

DashCaddy includes 78 pre-configured templates:

Media & Entertainment

• Plex, Jellyfin, Emby
• Navidrome, Airsonic
• Tautulli, Overseerr

Downloads

• Sonarr, Radarr, Lidarr, Readarr
• Prowlarr, Bazarr
• qBittorrent, Transmission
• SABnzbd, NZBGet

Productivity

• Nextcloud
• Paperless-ngx
• BookStack, Outline
• Standard Notes

Management

• Portainer
• Homepage, Homarr
• Uptime Kuma
• Grafana

Security & Authentication

• Vaultwarden (Password Manager)

Development

• Gitea
• VS Code Server
• Jenkins, Drone CI

And many more!

API Endpoints

Services

• GET /api/v1/services - List all services
• POST /api/v1/services - Add service
• PUT /api/v1/services - Bulk import services
• DELETE /api/v1/services/:id - Remove service

App Deployment

• GET /api/v1/apps/templates - List app templates
• POST /api/v1/apps/deploy - Deploy new app
• DELETE /api/v1/apps/:appId - Remove deployed app

Error Logs

• GET /api/v1/error-logs - Get error logs
• DELETE /api/v1/error-logs - Clear error logs

DNS Management

• POST /api/v1/dns/record - Create DNS record
• DELETE /api/v1/dns/record - Delete DNS record
• GET /api/v1/dns/records - List DNS records (active provider)

Reverse Proxy & Caddy Management

• GET /api/v1/caddy/config - Get Caddyfile content
• POST /api/v1/caddy/reload - Reload Caddy configuration
• GET /api/v1/caddy/cas - List upstream Caddy servers
• POST /api/v1/caddycode/generate - Generate a Caddyfile site block
• POST /api/v1/caddycode/validate - Validate a site-block config
• GET /api/v1/caddycode/templates - Preset configs for common patterns

Endpoint accuracy: the MCP route-existence drift gate (__tests__/mcp/mcp-core-dc166-integration.test.js) verifies every MCP tool's handler-issued API call against the declared routes; the entries above were additionally spot-checked against the router, and the full generated inventory lives in API-SURFACE.md.

Troubleshooting

SSL Certificate Errors

Problem: "Secure Connection Failed" when accessing new service

Solution:

• Wait 30-60 seconds for certificate generation
• Check dashboard notification for SSL status
• Manually reload Caddy: caddy reload --config /path/to/Caddyfile
• Check error logs in dashboard

DNS Not Resolving

Problem: Service URL doesn't resolve

Solution:

• Verify DNS server is running
• Check DNS credentials in 🔑 Tokens menu
• Manually add DNS record in Technitium DNS
• Flush DNS cache: ipconfig /flushdns (Windows) or sudo systemd-resolve --flush-caches (Linux)

Container Won't Start

Problem: Deployment succeeds but service is offline

Solution:

• Check Docker logs: docker logs [container-id]
• Verify port isn't already in use
• Check container resource limits
• View error logs in dashboard

Import/Export Issues

Problem: Import fails or data is incomplete

Solution:

• Validate JSON format
• Check file has version and services fields
• Reconfigure API tokens after import
• Check error logs for details

Development

Project Structure

dashcaddy/
├── status/                 # Dashboard frontend
│   ├── index.html         # Main dashboard
│   └── assets/            # Logos, icons, fonts
├── dashcaddy-api/         # API backend
│   ├── server.js          # Express server
│   ├── src/docker/app-templates.js   # App template definitions
│   └── package.json       # Dependencies
├── dashcaddy-installer/   # Electron installer (WIP)
└── docs/                  # Documentation

Adding Custom App Templates

Edit dashcaddy-api/src/docker/app-templates.js:

"myapp": {
  name: "My App",
  description: "Description of my app",
  icon: "🚀",
  logo: "https://cdn.example.com/logo.png",
  category: "Productivity",
  docker: {
    image: "myapp/myapp:latest",
    ports: ["{{PORT}}:8080"],
    volumes: ["/opt/myapp:/data"],
    environment: {
      "APP_ENV": "production"
    }
  },
  subdomain: "myapp",
  defaultPort: 8080,
  healthCheck: "/health"
}

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

Roadmap

• Service groups/categories
• Container log viewer
• DNS management UI (DC-166)
• Backup automation (schedules + point-in-time restore)
• Multi-user support (DC-048 — opt-in via siteConfig.authProviders.email.enabled; bootstrap admin, allowlist, invites)
• Mobile app
• Analytics dashboard
• Template marketplace

License

Proprietary software. All rights reserved. See LICENSE for the End-User License Agreement (EULA).

Credits

• Dashboard Icons: walkxcode/dashboard-icons (MIT License)
• Caddy: caddyserver.com
• Technitium DNS: technitium.com/dns

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Wiki

Acknowledgments

Built with ❤️ for the self-hosting community.

---

DashCaddy - Making self-hosting beautiful and effortless.