# Sovereign Orchestrator

**Automated Proxmox VE deployment and ISO build service by Theta42.**

A web-based orchestration platform that automates the creation of custom Proxmox VE auto-installer ISOs and manages VM deployments through a premium dark-mode GUI and REST API.

## Features

- **ISO Builder**: Generate custom Proxmox VE 9.1.x auto-installer ISOs with pre-configured `answers.toml`
- **VM Deployment**: Automated VM lifecycle management (create, start, stop, destroy) via Proxmox API
- **Build Pipeline**: Visual build status tracking with real-time log streaming
- **VM Control Panel**: Direct VM management with status monitoring
- **REST API**: Full programmatic access to all orchestrator functions
- **Premium GUI**: Sleek dark-mode interface with glassmorphism design

## Architecture

```
┌─────────────────────────────────┐
│     Frontend (Vanilla JS)       │
│  Dark Mode Dashboard + Forms    │
├─────────────────────────────────┤
│     FastAPI Backend (Python)    │
│  REST API + Static File Server  │
├──────────┬──────────────────────┤
│ ISO      │ Proxmox VE API      │
│ Builder  │ Client (httpx)      │
└──────────┴──────────────────────┘
         │              │
    ┌────┴────┐   ┌────┴────────┐
    │ xorriso │   │ Proxmox VE  │
    │ PVE ISO │   │ Host API    │
    └─────────┘   └─────────────┘
```

## Quick Start

### Prerequisites

- Python 3.11+
- `xorriso` (for ISO manipulation)
- `proxmox-auto-install-assistant` (from Proxmox repos)
- Proxmox VE API token (see [Configuration](#configuration))

### Install & Run

```bash
# Clone
git clone ssh://gitea@git.theta42.com:2222/nova/sovereign-orchestrator.git
cd sovereign-orchestrator

# Install dependencies
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Run
uvicorn app.main:app --host 0.0.0.0 --port 8888
```

Open `http://localhost:8888` in your browser.

### Production Deployment

```bash
# Run as root on the target LXC container
sudo bash setup.sh
sudo systemctl start sovereign-orchestrator
```

## Configuration

### Proxmox Credentials

Create `~/.proxmox-credentials`:

```bash
PROXMOX_HOST=https://your-pve-host:8006
PROXMOX_TOKEN_ID=user@pam!tokenname
PROXMOX_TOKEN_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
```

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `PROXMOX_HOST` | (from credentials file) | Proxmox VE API URL |
| `PROXMOX_TOKEN_ID` | (from credentials file) | API token ID |
| `PROXMOX_TOKEN_SECRET` | (from credentials file) | API token secret |
| `ISO_STORAGE_PATH` | `/var/lib/vz/template/iso` | Path to ISO storage |
| `DEFAULT_NODE` | `dl380-0` | Default Proxmox node |
| `DEFAULT_VMID` | `900` | Default VM ID for deployments |

## API Reference

### System Status
```
GET /api/status
```

### ISO Generation
```
POST /api/generate-iso
Content-Type: application/json

{
  "fqdn": "pve.example.com",
  "keyboard": "en-us",
  "country": "us",
  "timezone": "America/New_York",
  "mailto": "admin@example.com",
  "root_password": "secure-password",
  "root_ssh_keys": ["ssh-rsa AAAA..."],
  "network_source": "from-dhcp",
  "filesystem": "ext4",
  "disk_list": ["sda"]
}
```

### VM Deployment
```
POST /api/deploy
Content-Type: application/json

{
  "vmid": 900,
  "node": "dl380-0",
  "cores": 4,
  "memory": 8192,
  "disk_size": "64G"
}
```

### Build Status
```
GET /api/builds
GET /api/builds/{build_id}
```

### VM Control
```
GET  /api/vm/{vmid}/status
POST /api/vm/{vmid}/start
POST /api/vm/{vmid}/stop
```

### ISO Listing
```
GET /api/isos
```

## Project Structure

```
sovereign-orchestrator/
├── app/
│   ├── __init__.py
│   ├── main.py            # FastAPI application & routes
│   ├── config.py           # Configuration management
│   ├── models.py           # Pydantic data models
│   ├── proxmox_client.py   # Proxmox VE API client
│   └── iso_builder.py      # ISO generation logic
├── static/
│   ├── index.html          # Single-page application
│   ├── style.css           # Premium dark-mode styles
│   └── app.js              # Frontend application logic
├── setup.sh                # Production deployment script
├── requirements.txt        # Python dependencies
└── README.md               # This file
```

## License

Proprietary - Theta42