dashcaddy/status/DEPLOYMENT_GUIDE.md

# SAMI-CLOUD Status Dashboard - Deployment Guide

Complete guide for deploying and using the SAMI-CLOUD Status Dashboard with app deployment capabilities.

## Overview

The SAMI-CLOUD Status Dashboard is a web application that:
- Monitors service status in real-time
- Provides weather information
- Allows deploying new apps via a user-friendly interface
- Automatically creates DNS records and Caddy reverse proxy configurations
- Works cross-platform (Windows, Linux, macOS)

## Architecture

```
┌─────────────────────────────────────────────────────────┐
│                    User Browser                         │
│              (https://status.sami)                      │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│                  Caddy Server                           │
│  - Serves static files (index.html, assets)             │
│  - Proxies /api/* to Node.js API server                 │
│  - Provides TLS with internal CA                        │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│            Node.js API Server (port 3001)               │
│  - Handles app deployment requests                      │
│  - Creates DNS records via Technitium API               │
│  - Configures Caddy routes via Admin API                │
└───────┬─────────────────────────────┬───────────────────┘
        │                             │
        ▼                             ▼
┌──────────────────┐         ┌──────────────────┐
│ Caddy Admin API  │         │ Technitium DNS   │
│  (port 2019)     │         │  API (port 5380) │
└──────────────────┘         └──────────────────┘
```

## Prerequisites

1. **Caddy Server** with Admin API enabled
2. **Node.js** v14 or higher
3. **Technitium DNS Server** (optional, for DNS management)
4. **npm** (comes with Node.js)

## Step 1: Configure Caddy

### 1.1 Enable Caddy Admin API

Add to your Caddyfile (global options):

```caddyfile
{
  admin localhost:2019 {
    origins localhost localhost:2019
  }
}
```

### 1.2 Configure Status Dashboard Site

Add this block to your Caddyfile:

```caddyfile
status.sami {
  tls internal

  # API proxy to Node.js server
  handle /api/* {
    reverse_proxy localhost:3001
  }

  # Probe endpoints for service status checks
  handle_path /probe/* {
    header Content-Type application/json
    respond `{"ok":true}` 200
  }

  # Static site
  root * C:/caddy/sites/status
  file_server
}
```

### 1.3 Reload Caddy

```bash
caddy reload --config /path/to/Caddyfile
```

## Step 2: Deploy Dashboard Files

### 2.1 Copy Files to Production

Copy the status dashboard files to your Caddy web root:

```bash
# On Windows
xcopy /E /I e:\CaddyCerts\sites\status C:\caddy\sites\status

# On Linux/macOS
cp -r /path/to/development/sites/status /var/www/status
```

### 2.2 Verify File Structure

```
C:/caddy/sites/status/
├── index.html
├── apps.json
├── sw.js
├── assets/
│   ├── fonts/
│   ├── weather/
│   ├── *.png (app logos)
│   └── ...
└── api/
    ├── caddy-api.js
    ├── package.json
    ├── README.md
    └── node_modules/
```

## Step 3: Set Up API Server

### 3.1 Install Dependencies

```bash
cd C:/caddy/sites/status/api  # or your path
npm install
```

### 3.2 Configure Environment Variables

#### Windows (PowerShell - Persistent)
```powershell
# Set system environment variables
[System.Environment]::SetEnvironmentVariable('CADDY_ADMIN_API', 'http://localhost:2019', 'User')
[System.Environment]::SetEnvironmentVariable('DNS_SERVER_API', 'http://192.168.254.204:5380', 'User')
[System.Environment]::SetEnvironmentVariable('TECHNITIUM_API_TOKEN', 'your_token_here', 'User')
```

#### Linux/macOS (Persistent)
Add to `~/.bashrc` or `~/.zshrc`:

```bash
export CADDY_ADMIN_API=http://localhost:2019
export DNS_SERVER_API=http://192.168.254.204:5380
export TECHNITIUM_API_TOKEN=your_token_here
```

Then reload:
```bash
source ~/.bashrc  # or source ~/.zshrc
```

### 3.3 Get Technitium API Token

1. Open Technitium DNS web interface (e.g., `http://dns1.sami:5380`)
2. Log in with admin credentials
3. Go to **Settings → API**
4. Generate a new token or copy existing one
5. Set as `TECHNITIUM_API_TOKEN` environment variable

### 3.4 Test the API Server

```bash
node test-api.js
```

Expected output:
```
Testing SAMI-CLOUD API...

1. Testing health endpoint...
   ✓ Health check passed

2. Testing API test endpoint...
   ✓ API test passed
   Platform: win32
   Caddy Admin API: http://localhost:2019
   DNS Server API: http://192.168.254.204:5380
   DNS Token: Configured

3. Testing services endpoint...
   ✓ Services endpoint passed
   Found 8 services

Tests complete!
```

## Step 4: Run the API Server

### Option A: Run Directly (for testing)

```bash
node caddy-api.js
```

### Option B: Use PM2 (recommended for production)

```bash
# Install PM2 globally
npm install -g pm2

# Start the API server
pm2 start caddy-api.js --name sami-api

# Save the process list
pm2 save

# Set up PM2 to start on boot
pm2 startup
```

Manage with PM2:
```bash
pm2 status         # Check status
pm2 logs sami-api  # View logs
pm2 restart sami-api
pm2 stop sami-api
```

### Option C: Windows Service (using PM2)

```bash
npm install -g pm2-windows-service
pm2-service-install -n SAMI-API
```

### Option D: systemd (Linux)

Create `/etc/systemd/system/sami-api.service`:

```ini
[Unit]
Description=SAMI-CLOUD API Server
After=network.target

[Service]
Type=simple
User=caddy
WorkingDirectory=/var/www/status/api
Environment="NODE_ENV=production"
Environment="CADDY_ADMIN_API=http://localhost:2019"
Environment="DNS_SERVER_API=http://192.168.254.204:5380"
Environment="TECHNITIUM_API_TOKEN=your_token"
ExecStart=/usr/bin/node caddy-api.js
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target
```

Enable and start:
```bash
sudo systemctl daemon-reload
sudo systemctl enable sami-api
sudo systemctl start sami-api
sudo systemctl status sami-api
```

## Step 5: Verify Everything Works

### 5.1 Access the Dashboard

Open your browser and navigate to:
```
https://status.sami
```

You should see:
- Service status cards
- Weather widget
- Theme toggle
- "📱 App Selector" button

### 5.2 Test App Deployment

1. Click **"📱 App Selector"** button
2. Choose an app template (or use the generic one)
3. Fill in the deployment form:
   - **Subdomain**: e.g., `test-app`
   - **IP Address**: e.g., `192.168.1.100`
   - **Port**: e.g., `8080`
   - **DNS Type**: Choose "Private DNS" or "Public DNS"
   - **SSL Type**: Choose "Internal CA" or "Public (Let's Encrypt)"
4. Click **"Deploy App"**

If successful, you should see:
- Success message
- New card appears in the grid
- App is accessible at `https://test-app.sami`

## Troubleshooting

### Dashboard not accessible
- Check Caddy is running: `caddy version`
- Check Caddyfile syntax: `caddy validate --config /path/to/Caddyfile`
- View Caddy logs for errors

### API requests failing
- Verify API server is running: `pm2 status` or check process
- Check API logs: `pm2 logs sami-api`
- Test API directly: `curl http://localhost:3001/health`

### DNS records not created
- Verify `TECHNITIUM_API_TOKEN` is set correctly
- Test DNS API manually:
  ```bash
  curl "http://192.168.254.204:5380/api/zones/records/get?token=YOUR_TOKEN&domain=sami"
  ```
- Check Technitium DNS server is running

### Caddy routes not working
- Verify Caddy Admin API is accessible:
  ```bash
  curl http://localhost:2019/config/
  ```
- Check Caddy admin API origins in Caddyfile
- View Caddy configuration: `curl http://localhost:2019/config/ | jq .`

### App deployment fails
1. Check API server logs
2. Verify all environment variables are set
3. Test each component individually:
   - DNS API connection
   - Caddy Admin API connection
4. Check for existing configurations with same subdomain

## Advanced Configuration

### Custom App Templates

Edit the dashboard's JavaScript to add custom app templates with pre-configured settings.

### Multiple DNS Servers

Modify the API to support multiple DNS servers for redundancy.

### Docker Integration

Extend the API to deploy Docker containers automatically before configuring DNS and Caddy.

### Authentication

Add authentication middleware to the API server to protect deployment endpoints.

## Maintenance

### Backup Important Files

Regularly backup:
- `C:/caddy/Caddyfile` (or equivalent)
- `C:/caddy/sites/status/apps.json`
- Custom app data in localStorage (export from browser)

### Update the Dashboard

1. Pull latest changes from development
2. Copy updated files to production
3. Restart API server if needed
4. Clear browser cache or bump cache version in `sw.js`

### Monitor Logs

```bash
# API logs
pm2 logs sami-api

# Caddy logs
caddy logs

# System logs (Linux)
journalctl -u sami-api -f
```

## Security Considerations

1. **API Access**: The API server should only be accessible from localhost or trusted networks
2. **DNS Token**: Keep your Technitium API token secure
3. **Caddy Admin API**: Restrict access to localhost only
4. **CORS**: The API has CORS enabled - restrict origins in production
5. **Input Validation**: The API validates inputs but consider additional security layers

## Support

For issues or questions:
- Check the API README: `api/README.md`
- Review Caddy documentation: https://caddyserver.com/docs/
- Check Technitium DNS docs: https://technitium.com/dns/

## License

MIT