wip: Windows desktop app scaffold (WinUI 3/.NET 8) + NSIS installer + docs
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).
This commit is contained in:
Hermes
+148
@@ -0,0 +1,148 @@
|
||||
# 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` |
|
||||
Reference in New Issue
Block a user