dashcaddy/status/api/README.md

SAMI-CLOUD Status Dashboard API

Cross-platform Node.js API server for managing Caddy reverse proxy and DNS records via REST APIs.

Features

• Cross-Platform: Works on Windows, Linux, and macOS
• API-Based: Uses Caddy Admin API and Technitium DNS API (no PowerShell required)
• App Deployment: Deploy apps by creating DNS records and Caddy reverse proxy routes
• App Deletion: Clean removal of DNS records and Caddy routes
• Automatic Rollback: If deployment fails, automatically rolls back changes

Prerequisites

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

Installation

cd api
npm install

Configuration

Set the following environment variables (or use defaults):

# Caddy Admin API endpoint (default: http://localhost:2019)
export CADDY_ADMIN_API=http://localhost:2019

# Technitium DNS Server API endpoint (default: http://192.168.254.204:5380)
export DNS_SERVER_API=http://192.168.254.204:5380

# Technitium DNS API token (required for DNS operations)
export TECHNITIUM_API_TOKEN=your_api_token_here

Windows (PowerShell)

$env:CADDY_ADMIN_API="http://localhost:2019"
$env:DNS_SERVER_API="http://192.168.254.204:5380"
$env:TECHNITIUM_API_TOKEN="your_api_token_here"

Windows (Command Prompt)

set CADDY_ADMIN_API=http://localhost:2019
set DNS_SERVER_API=http://192.168.254.204:5380
set TECHNITIUM_API_TOKEN=your_api_token_here

Running the Server

npm start

Or directly:

node caddy-api.js

The server will start on port 3001.

API Endpoints

Deploy an App

POST /api/apps/deploy
Content-Type: application/json

{
  "appId": "myapp",
  "config": {
    "subdomain": "myapp",
    "ip": "192.168.1.100",
    "port": "8080",
    "createDns": true,
    "dnsType": "private",
    "sslType": "internal"
  }
}

Response:

{
  "success": true,
  "message": "App myapp deployed successfully",
  "url": "https://myapp.sami",
  "domain": "myapp.sami",
  "ip": "192.168.1.100",
  "port": "8080",
  "dnsCreated": true,
  "caddyConfigured": true
}

Delete an App

POST /api/apps/delete
Content-Type: application/json

{
  "domain": "myapp.sami",
  "ip": "192.168.1.100"
}

Get Services List

GET /api/services

Get Caddy Configuration

GET /api/caddy/config

Test API

GET /api/caddy/test

Health Check

GET /health

Caddy Configuration Requirements

Your Caddyfile should have the Admin API enabled:

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

For the status dashboard to proxy API requests, add this to your Caddyfile:

status.sami {
  tls internal

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

  # Static site
  root * /path/to/sites/status
  file_server
}

Getting Technitium DNS API Token

1. Open Technitium DNS web interface
2. Go to Settings → API
3. Create a new API token or copy existing one
4. Set it as the TECHNITIUM_API_TOKEN environment variable

Deployment Flow

When deploying an app:

1. Validate - Checks required fields (appId, subdomain, ip)
2. DNS Record - Creates A record in DNS (if createDns: true and dnsType: "private")
3. Caddy Route - Adds reverse proxy route via Caddy Admin API
4. Rollback - If Caddy configuration fails, removes DNS record

Troubleshooting

Caddy Admin API not accessible

• Verify Caddy is running
• Check that admin API is enabled in your Caddyfile
• Confirm the CADDY_ADMIN_API URL is correct

DNS operations failing

• Verify TECHNITIUM_API_TOKEN is set correctly
• Check DNS_SERVER_API URL is accessible
• Ensure the API token has permissions to manage zones

Routes not appearing in Caddy

• Check Caddy logs: caddy logs
• Verify the route was added: curl http://localhost:2019/config/
• Ensure the domain resolves correctly in DNS

Production Deployment

For production use:

1. Set up environment variables persistently
2. Use a process manager (PM2, systemd, etc.)
3. Configure proper logging
4. Set up SSL/TLS for the API if exposed externally

Using PM2

npm install -g pm2
pm2 start caddy-api.js --name sami-api
pm2 save
pm2 startup

Using systemd (Linux)

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

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

[Service]
Type=simple
User=caddy
WorkingDirectory=/path/to/sites/status/api
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

[Install]
WantedBy=multi-user.target

Then:

sudo systemctl enable sami-api
sudo systemctl start sami-api

License

MIT