wmantly
70c71161f3
- FastAPI backend with full Proxmox VE API integration - ISO builder using proxmox-auto-install-assistant - Premium dark-mode SPA frontend with glassmorphism design - VM lifecycle management (create, start, stop, destroy) - Build pipeline tracking with real-time logs - Deployment automation for custom auto-installer ISOs - Production deployment script (setup.sh + systemd) - Comprehensive README with API documentation
174 lines
4.7 KiB
Markdown
174 lines
4.7 KiB
Markdown
# 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 |