Initial commit: DashCaddy v1.0
Full codebase including API server (32 modules + routes), dashboard frontend, DashCA certificate distribution, installer script, and deployment skills.
This commit is contained in:
230
CLAUDE.md
Normal file
230
CLAUDE.md
Normal file
@@ -0,0 +1,230 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user