dashcaddy/CLAUDE.md

# DashCaddy Project Guidelines for AI Assistants

## HARD RULE: Docker Storage on E: Drive

**ALL Docker container data, volumes, bind mounts, and app configs MUST use `E:/dockerdata/` via bind mounts or CIFS volumes. No exceptions.**

- E: is a network share (`\\Sami-pc\e_share`) shared across all home network computers
- The ONLY thing allowed on C: is the Docker Desktop WSL engine VHD (`C:/dockerdata/DockerDesktopWSL/`) — this is the absolute bare minimum WSL2 requires (local NTFS). WSL2 cannot create VHDs on network shares.
- Keep C: Docker usage under 5GB
- When deploying new containers, always use `E:/dockerdata/<app-name>/` for bind mount paths
- For CIFS volumes in docker-compose, use `//Sami-pc/e_share/dockerdata/...` as the device path

## CRITICAL: Production vs Development Paths

### Production Files (LIVE - what actually runs)
```
C:/caddy/
├── Caddyfile              # Active Caddy configuration
├── services.json          # Services shown on dashboard
├── dns-credentials.json   # DNS API credentials
├── config.json            # DashCaddy configuration
└── sites/
    └── status/            # Dashboard frontend files
        └── assets/        # Logos, fonts, icons
```

### Development Files (for editing/testing)
```
e:/CaddyCerts/sites/
├── caddy-api/
│   ├── server.js          # API server source code
│   ├── app-templates.js   # Docker app templates (52+ apps)
│   ├── services.json      # DEV ONLY - not used in production!
│   └── ...
└── status/
    └── index.html         # Dashboard UI source
```

## Docker Container Mount Points

The `caddy-api` container mounts production files:

| Container Path | Host Path (Production) |
|----------------|------------------------|
| `/app/services.json` | `C:/caddy/services.json` |
| `/app/dns-credentials.json` | `C:/caddy/dns-credentials.json` |
| `/caddyfile` | `C:/caddy/Caddyfile` |
| `/app/assets` | `C:/caddy/sites/status/assets` |

## When Making Changes

### To add/remove services from dashboard:
Edit `C:/caddy/services.json` (NOT e:/CaddyCerts/sites/caddy-api/services.json)

### To modify Caddy reverse proxy rules:
Edit `C:/caddy/Caddyfile`, then reload via:
```bash
curl -X POST http://localhost:2019/load -H "Content-Type: text/caddyfile" --data-binary @"C:/caddy/Caddyfile"
```

### To modify API server code:
Edit `e:/CaddyCerts/sites/caddy-api/server.js`, then:
1. Copy to production: `C:/caddy/sites/caddy-api/`
2. Restart container: `docker restart caddy-api`

### To modify app templates:
Edit `e:/CaddyCerts/sites/caddy-api/app-templates.js`
(Templates are loaded at runtime, changes require container restart)

### To modify dashboard UI:
Edit `e:/CaddyCerts/sites/status/index.html`
Copy to `C:/caddy/sites/status/` for production

### To modify DashCA (CA certificate distribution):
Edit files in `e:/CaddyCerts/sites/ca/`, then:
1. Regenerate certificate formats: `cd e:/CaddyCerts/sites/ca/scripts && bash generate-all.sh`
2. Copy to production: `cp -r e:/CaddyCerts/sites/ca/* C:/caddy/sites/ca/`
3. Reload Caddy if Caddyfile changes were made

## DashCA - Certificate Authority Distribution

**Purpose**: Provides a one-click installation page for the root CA certificate, allowing users to easily trust *.sami domains on any device.

**Access**: https://ca.sami (or https://ca.yourdomain for other installations)

### File Locations

**Development (for editing):**
```
e:/CaddyCerts/sites/ca/
├── index.html                   # Landing page
├── root.crt, root.der           # Certificate formats
├── root.mobileconfig            # Apple profile
├── intermediate.crt             # Intermediate CA
├── cert-info.json               # Certificate metadata
├── scripts/
│   ├── install.ps1              # Windows installer
│   ├── install.sh               # Linux/macOS installer
│   ├── generate-cert-info.js    # Extract cert metadata
│   ├── generate-mobileconfig.js # Generate Apple profile
│   └── generate-all.sh          # Regenerate all formats
└── assets/                      # Icons, logos
```

**Production (served by Caddy):**
```
C:/caddy/sites/ca/
├── index.html
├── root.crt, root.der
├── root.mobileconfig
├── install.ps1, install.sh
└── assets/
```

### Certificate Source

Caddy's built-in PKI generates certificates at:
- **Root CA**: `C:/caddy/certs/pki/authorities/local/root.crt`
- **Intermediate CA**: `C:/caddy/certs/pki/authorities/local/intermediate.crt`

**Certificate Info:**
- **CN**: Sami Home Network Root CA
- **Algorithm**: ECDSA P-256 with SHA-256
- **Valid Until**: Dec 22, 2034 (~10 years)
- **Fingerprint**: `08:98:A5:63:F5:A1:A2:58:5F:02:D7:A8:A2:54:87:E6:BC:33:96:21:29:0E`

### Deployment

DashCA is a **static site** (not Docker-based), deployed via the app selector:
1. Navigate to App Selector in dashboard
2. Find "DashCA" in Security category
3. Click Deploy
4. System automatically:
   - Creates `C:/caddy/sites/ca/` directory
   - Copies files from development directory
   - Generates certificate formats (DER, mobileconfig)
   - Adds ca.sami block to Caddyfile
   - Reloads Caddy configuration
   - Registers service in `services.json`

### Updating Certificates

When Caddy's CA certificate is renewed (every ~10 years):

```bash
# 1. Regenerate all certificate formats
cd e:/CaddyCerts/sites/ca/scripts
bash generate-all.sh

# 2. Update fingerprint in installation scripts
# Edit install.ps1 - update $ExpectedFingerprint
# Edit install.sh - update EXPECTED_FP

# 3. Copy to production
cp -r e:/CaddyCerts/sites/ca/* C:/caddy/sites/ca/

# 4. Notify users via dashboard or email
```

### API Endpoints

- **GET /api/ca/info** - Returns certificate metadata (name, fingerprint, expiration, etc.)
- **GET /api/health/ca** - Returns CA expiration health status
  - `healthy`: >90 days remaining
  - `warning`: 30-90 days remaining
  - `critical`: <30 days remaining

### Caddyfile Configuration

DashCA's Caddyfile block (auto-generated on deployment):
- **Root**: `C:/caddy/sites/ca`
- **TLS**: Internal (uses Caddy's local CA)
- **MIME Types**: Proper headers for .crt, .der, .mobileconfig, .ps1, .sh files
- **SPA Fallback**: Rewrites non-file requests to /index.html
- **Cache Control**: Certificates cached for 24h, HTML not cached

### Supported Platforms

- **Windows**: PowerShell installer (installs to LocalMachine\Root store)
- **macOS**: .mobileconfig profile or command-line installer
- **Linux**: Shell installer (Debian, RedHat, Arch)
- **iOS**: .mobileconfig profile (requires manual trust in Settings)
- **Android**: Direct .crt download (installs as user certificate)

### Landing Page Features

- Automatic OS detection
- QR code for mobile access
- Certificate info display (loaded from `/api/ca/info`)
- Platform-specific installation instructions
- Copy-to-clipboard for fingerprint and commands
- Download links for all certificate formats

### Troubleshooting

**Issue**: Certificate fingerprint mismatch during installation
**Cause**: CA certificate was renewed
**Solution**: Regenerate certificates and update fingerprints in install scripts

**Issue**: *.sami sites still show warnings after CA install
**Cause**: Browser may have cached the untrusted state
**Solution**: Clear browser cache, restart browser, or visit site in incognito mode

**Issue**: iOS doesn't trust certificate after profile install
**Cause**: iOS requires manual trust enablement
**Solution**: Settings → General → About → Certificate Trust Settings → Enable trust

## Key Services

| Service | Port | Description |
|---------|------|-------------|
| Caddy (HTTPS) | 443 | Reverse proxy |
| Caddy Admin | 2019 | Caddy API (note: NOT 2021) |
| DashCaddy API | 3001 | Dashboard backend |
| DNS2 (Primary) | 100.74.102.61:5380 | Technitium DNS |
| DNS1 (Secondary) | 192.168.254.204:5380 | Technitium DNS |

## Common Mistakes to Avoid

1. **Wrong services.json**: The API container reads from `C:/caddy/services.json`, not the development copy
2. **Caddy admin port**: It's 2019, not 2021 (check with `netstat` if unsure)
3. **DNS server**: DNS2 (100.74.102.61) is PRIMARY, DNS1 is secondary
4. **Caddyfile not reloaded**: After editing, must POST to /load endpoint or restart Caddy

## Project Info

- **Name**: DashCaddy
- **Version**: 1.0
- **Purpose**: Unified management for Docker + Caddy + DNS
- **Local TLD**: .sami