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):

{
  admin localhost:2019 {
    origins localhost localhost:2019
  }
}

1.2 Configure Status Dashboard Site

Add this block to your 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

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:

# 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

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

3.2 Configure Environment Variables

Windows (PowerShell - Persistent)

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

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:

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

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)

node caddy-api.js

Option B: Use PM2 (recommended for production)

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

pm2 status         # Check status
pm2 logs sami-api  # View logs
pm2 restart sami-api
pm2 stop sami-api

Option C: Windows Service (using PM2)

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

Option D: systemd (Linux)

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

[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:

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:

  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:

  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

# 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