feat: initial orchestrator service with FastAPI backend and premium GUI
- 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
This commit is contained in:
@@ -1,3 +1,174 @@
|
||||
# sovereign-orchestrator
|
||||
# Sovereign Orchestrator
|
||||
|
||||
Sovereign Box Orchestrator - API and GUI to automate Proxmox VE auto-installer ISO builds and deployments
|
||||
**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
|
||||
Reference in New Issue
Block a user