dashcaddy/INSTALL.md

DashCaddy — Cross-Platform Installation Guide

One-Line Install (Linux/macOS/WSL)

curl -fsSL https://dashcaddy.net/install.sh | bash

One-Line Install (Windows PowerShell)

irm https://dashcaddy.net/install.ps1 | iex

What Gets Installed

Component	Purpose
Caddy	Reverse proxy + TLS termination (automatic HTTPS via Let's Encrypt)
DashCaddy API	Node.js backend (Docker, DNS, services management)
Dashboard	Single-page React-free frontend (served by Caddy)
DashCA	Local CA for *.local / *.home / *.sami trust

Prerequisites

Platform	Requirements
Linux (Debian/Ubuntu/Alpine/RHEL/Fedora/Arch)	curl, docker, docker-compose (v2 plugin)
macOS (Intel/Apple Silicon)	curl, docker (Docker Desktop or Colima)
Windows 10/11 Pro/Enterprise	WSL2 + Docker Desktop or native Windows containers
Windows 10/11 Home	WSL2 required (Docker Desktop uses WSL2 backend)

Note

: On Windows, the installer sets up WSL2 + Ubuntu if not present, then runs the Linux install inside WSL. Native Windows containers are supported but WSL2 is recommended for compatibility.

Post-Install

1. Open https://status.<your-domain> (or https://status.local for local-only)
2. Run the Setup Wizard (auto-shown on first visit)
3. Add your first service — Done.

Advanced: Manual Docker Compose

# Clone repo
git clone https://git.dashcaddy.net/sami7777/dashcaddy.git
cd dashcaddy

# Copy config template
cp config.example.yaml config.yaml
# Edit config.yaml — at minimum set: domain, email, timezone

# Start (detached)
docker compose --profile prod up -d

# View logs
docker compose logs -f dashcaddy-api

Config File: config.yaml

# DashCaddy Configuration
# All values can be overridden by environment variables (see ENVIRONMENT.md)

domain: "example.com"          # Your base domain (required)
email: "admin@example.com"     # Let's Encrypt registration (required)
timezone: "America/Los_Angeles"

# Optional overrides
caddy:
  admin_port: 2019
  http_port: 80
  https_port: 443

dashcaddy:
  api_port: 3001
  data_dir: "/opt/dashcaddy/data"    # Linux default
  # data_dir: "E:/dockerdata/dashcaddy"  # Windows default (E: drive)

dns:
  provider: "coredns"              # or "technitium", "cloudflare", "route53"
  # provider_config: {}            # See DNS_PROVIDERS.md

# Feature flags (all opt-in)
features:
  multi_user: false          # Enable user accounts + invites
  billing: false             # Enable Stripe billing (requires Stripe keys)
  share: false               # Enable Tailscale share links
  ca: true                   # Enable DashCA local CA page

# Security
security:
  totp_required: true        # Require TOTP for all logins
  session_timeout: "24h"
  csrf_protection: true

Directory Layout (After Install)

/opt/dashcaddy/                    # Linux/macOS/WSL data root
├── config.yaml                    # Main config (edit this)
├── data/
│   ├── services.json              # Service definitions (auto-managed)
│   ├── credentials.json.enc       # Encrypted app credentials
│   └── .encryption-key            # AES-256 key (keep secret!)
├── caddy/
│   ├── Caddyfile                  # Generated from config.yaml + services
│   └── certs/                     # Let's Encrypt certificates
├── dashca/                        # Local CA static site
└── backups/                       # Automatic backups

E:\dockerdata\dashcaddy\           # Windows data root (same structure)

Upgrading

# One-liner (re-runs installer, preserves data)
curl -fsSL https://dashcaddy.net/install.sh | bash

# Or via compose
docker compose pull && docker compose --profile prod up -d

Uninstalling

# Linux/macOS/WSL
/opt/dashcaddy/uninstall.sh

# Windows
C:\dashcaddy\uninstall.ps1

Removes containers, networks, and optionally data directory (with confirmation).

---

Troubleshooting

Issue	Fix
Port 80/443 in use	Stop existing nginx/apache, or change caddy.http_port/caddy.https_port in config.yaml
"Permission denied" on Docker	Add user to docker group: sudo usermod -aG docker $USER then relogin
Windows: "WSL2 not found"	Run installer as Admin — it will enable WSL2 and install Ubuntu
Certificates not issuing	Check DNS A/AAAA records point to this machine; ensure ports 80/443 reachable
Dashboard shows "Offline"	Verify docker compose ps shows dashcaddy-api healthy; check docker compose logs dashcaddy-api