# 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` |