d-bis/proxmox
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Phoenix Deploy API: OpenAPI spec, Swagger UI at /api-docs, railing and health routes
Some checks failed
Deploy to Phoenix / deploy (push) Has been cancelled
Details

Browse Source 
- openapi.yaml, docs/index.html; GET /api-docs and /api-docs/spec.yaml
- Health, Infra, VE, VM lifecycle, Prometheus proxy, webhook
- docs/00-meta/SANKOFA_API_COMPLETE_TASK_LIST.md

Made-with: Cursor
This commit is contained in:
defiQUG
2026-03-11 12:58:00 -07:00
parent 7df27bde32
commit 3e9645274a
13 changed files with 711 additions and 4313 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
phoenix-deploy-api/README.md
View File

@@ -8,8 +8,18 @@ Gitea webhook receiver and deploy endpoint stub for Gitea → Phoenix deployment
|--------|------|-------------|
| POST | /webhook/gitea | Receives Gitea push/tag/PR webhooks |
| POST | /api/deploy | Deploy request (repo, branch, target) |
| GET | /api/v1/infra/nodes | Cluster nodes (Proxmox; stub if PROXMOX_* unset) |
| GET | /api/v1/infra/storage | Storage pools (Proxmox; stub if unset) |
| GET | /api/v1/ve/vms | List VMs/CTs (optional `?node=`) |
| GET | /api/v1/ve/vms/:node/:vmid/status | VM/CT status (`?type=lxc` for containers) |
| POST | /api/v1/ve/vms/:node/:vmid/start, stop, reboot | VM/CT lifecycle (set PHOENIX_VE_LIFECYCLE_ENABLED=1) |
| GET | /api/v1/health/metrics | Prometheus query proxy (`?query=<PromQL>`) |
| GET | /api/v1/health/alerts | Active alerts (optional PROMETHEUS_ALERTS_URL) |
| GET | /api/v1/health/summary | Aggregated health for Portal |
| GET | /health | Health check |
All `/api/v1/*` routes accept optional partner API key when `PHOENIX_PARTNER_KEYS` is set (`X-API-Key` or `Authorization: Bearer <key>`).
## Environment
Copy `.env.example` to `.env` and set `GITEA_TOKEN` (and optionally `PHOENIX_DEPLOY_SECRET`).
@@ -20,6 +30,18 @@ Copy `.env.example` to `.env` and set `GITEA_TOKEN` (and optionally `PHOENIX_DEP
| GITEA_URL | https://gitea.d-bis.org | Gitea instance URL |
| GITEA_TOKEN | | Token for commit status API |
| PHOENIX_DEPLOY_SECRET | | Optional secret for webhook/deploy auth |
| PROXMOX_HOST | | Proxmox host (IP or hostname) for API Railing |
| PROXMOX_PORT | 8006 | Proxmox API port |
| PROXMOX_USER | root@pam | Proxmox API user |
| PROXMOX_TOKEN_NAME | | Proxmox API token name |
| PROXMOX_TOKEN_VALUE | | Proxmox API token secret |
| PROXMOX_TLS_VERIFY | 1 | Set to 0 to allow self-signed Proxmox certs |
| PHOENIX_VE_LIFECYCLE_ENABLED | 0 | Set to 1 to enable VM/CT start/stop/reboot |
| PROMETHEUS_URL | http://localhost:9090 | Prometheus base URL for Health API |
| PROMETHEUS_ALERTS_URL | (PROMETHEUS_URL)/api/v1/alerts | Optional; use Alertmanager URL for firing alerts |
| PHOENIX_WEBHOOK_URL | | Outbound webhook URL; POST deploy events with X-Phoenix-Signature |
| PHOENIX_WEBHOOK_SECRET | | Secret to sign webhook payloads (HMAC-SHA256) |
| PHOENIX_PARTNER_KEYS | | Comma-separated API keys for /api/v1/* (optional) |
## Gitea Webhook Configuration
@@ -43,6 +65,11 @@ curl -X POST "https://phoenix-api-host/api/deploy" \
This service is a standalone stub. Full deployment logic should be implemented in the Sankofa Phoenix API (VMID 8600). Migrate the webhook handler and deploy logic into the Phoenix API when ready.
## OpenAPI / Swagger
- **Spec:** [openapi.yaml](openapi.yaml)
- **HTML doc:** [docs/index.html](docs/index.html) — static Swagger UI; open locally or serve from `phoenix-deploy-api/docs/` (loads `../openapi.yaml`). To serve in-app, add `swagger-ui-express` and mount at e.g. `/api-docs`.
## Run
```bash