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

```bash
cd api
npm install
```

## Configuration

Set the following environment variables (or use defaults):

```bash
# 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)
```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)
```cmd
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

```bash
npm start
```

Or directly:
```bash
node caddy-api.js
```

The server will start on port 3001.

## API Endpoints

### Deploy an App
```http
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:**
```json
{
  "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
```http
POST /api/apps/delete
Content-Type: application/json

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

### Get Services List
```http
GET /api/services
```

### Get Caddy Configuration
```http
GET /api/caddy/config
```

### Test API
```http
GET /api/caddy/test
```

### Health Check
```http
GET /health
```

## Caddy Configuration Requirements

Your Caddyfile should have the Admin API enabled:

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

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

```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
```bash
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`:

```ini
[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:
```bash
sudo systemctl enable sami-api
sudo systemctl start sami-api
```

## License

MIT