Hermes
86e4c9fc81
Owner decision pending (STATE.md DC-100 tick): adopt/ship/park. Preserved from fragile git stash to named branch 2026-08-23. NOTE: requires a Windows build machine (WinUI XAML compiler + MSIX do not cross-build on Linux) — see WINDOWS_APP_BUILD.md in this tree. Secret-scanned clean 2026-08-23 (no keys/tokens/PEM in tree).
148 lines
4.6 KiB
Markdown
148 lines
4.6 KiB
Markdown
# DashCaddy — Cross-Platform Installation Guide
|
|
|
|
## One-Line Install (Linux/macOS/WSL)
|
|
|
|
```bash
|
|
curl -fsSL https://dashcaddy.net/install.sh | bash
|
|
```
|
|
|
|
## One-Line Install (Windows PowerShell)
|
|
|
|
```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
|
|
|
|
```bash
|
|
# 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`
|
|
|
|
```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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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` | |