refactor: Phase 1 code cleanup - constants, logging, and repository organization
This commit is contained in:
402
status/DEPLOYMENT_GUIDE.md
Normal file
402
status/DEPLOYMENT_GUIDE.md
Normal file
@@ -0,0 +1,402 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user