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
Some checks failed
Deploy to Phoenix / deploy (push) Has been cancelled
- 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
133
docs/00-meta/SANKOFA_API_COMPLETE_TASK_LIST.md
Normal file
133
docs/00-meta/SANKOFA_API_COMPLETE_TASK_LIST.md
Normal file
@@ -0,0 +1,133 @@
|
||||
# Complete Task List — Sankofa Phoenix API
|
||||
|
||||
**Purpose:** Single list of all tasks required to complete the API for Sankofa (GraphQL + REST railing, client API, docs, Gitea).
|
||||
**Last Updated:** 2026-03-11
|
||||
**Refs:** [PHOENIX_API_RAILING_TASKS.md](../02-architecture/PHOENIX_API_RAILING_TASKS.md), [PHOENIX_API_RAILING_SPEC.md](../02-architecture/PHOENIX_API_RAILING_SPEC.md), [SANKOFA_PHOENIX_GITEA_REPOS_REVIEW.md](../04-configuration/SANKOFA_PHOENIX_GITEA_REPOS_REVIEW.md)
|
||||
|
||||
---
|
||||
|
||||
## 1. Remaining Railing / Client API (Sankofa)
|
||||
|
||||
| # | Task | Owner | Priority | Notes |
|
||||
|---|------|--------|----------|--------|
|
||||
| 1.1 | **API key store (Vault or DB)** — key hash, tenant_id, scopes (read / read-write) for client and partner API keys | Sankofa / Operator | High | Blocking for 1.2. See PHOENIX_VAULT_CLUSTER_DEPLOYMENT; identity/JWT used today. |
|
||||
| 1.2 | **Issue API keys for Site24x7 users** (Gitea team → Phoenix API keys) | Operator | Optional | After 1.1. Per GITEA_TEAM_MEMBERS_API. |
|
||||
|
||||
---
|
||||
|
||||
## 2. Code and Repo Sync (Delivery)
|
||||
|
||||
| # | Task | Owner | Priority | Notes |
|
||||
|---|------|--------|----------|--------|
|
||||
| 2.1 | **Commit and push Sankofa API changes to Gitea** | Dev/Operator | High | Uncommitted: `api/src/routes/phoenix-railing.ts`, `api/src/server.ts`, migrations, typeDefs, sovereign-stack, setup docs. Push to `sankofa_phoenix` (and optionally `gitea` d-bis/Sankofa). |
|
||||
| 2.2 | **Re-sync Phoenix_API repo on Gitea** | Dev/Operator | High | After 2.1: `git subtree split -P api -b phoenix-api` then push to `Sankofa_Phoenix/Phoenix_API` so Gitea has latest API code. |
|
||||
| 2.3 | **Commit and push proxmox phoenix-deploy-api to Gitea** | Dev/Operator | Medium | Uncommitted: `openapi.yaml`, `docs/index.html`, README, server.js. Push to `gitea` (d-bis/proxmox). |
|
||||
|
||||
---
|
||||
|
||||
## 3. Configuration and Deployment
|
||||
|
||||
| # | Task | Owner | Priority | Notes |
|
||||
|---|------|--------|----------|--------|
|
||||
| 3.1 | **Set PHOENIX_RAILING_URL in Sankofa API** | Operator | High | Point to phoenix-deploy-api base URL (e.g. `http://phoenix-deploy-api:4001` or public URL) so Sankofa REST proxy works. |
|
||||
| 3.2 | **Set PHOENIX_RAILING_API_KEY (optional)** | Operator | Low | If phoenix-deploy-api enforces PHOENIX_PARTNER_KEYS, set this in Sankofa so server-to-server calls succeed. |
|
||||
| 3.3 | **Proxmox env on phoenix-deploy-api** | Operator | High | PROXMOX_HOST, PROXMOX_TOKEN_NAME, PROXMOX_TOKEN_VALUE (and optional PHOENIX_VE_LIFECYCLE_ENABLED=1, PROMETHEUS_URL) for live Infra/VE/Health. |
|
||||
|
||||
---
|
||||
|
||||
## 4. API Documentation
|
||||
|
||||
| # | Task | Owner | Priority | Notes |
|
||||
|---|------|--------|----------|--------|
|
||||
| 4.1 | **GraphQL schema export / interactive docs** | Sankofa | Medium | Publish schema (SDL or introspection JSON); add GraphQL Playground or Apollo Studio for interactive docs. |
|
||||
| 4.2 | **OpenAPI for GraphQL endpoint (optional)** | Sankofa | Low | Minimal OpenAPI describing POST /graphql; or keep schema as source of truth. |
|
||||
| 4.3 | **REST railing OpenAPI in Phoenix_API repo (optional)** | Sankofa | Low | Copy or link phoenix-deploy-api openapi.yaml into Sankofa/Phoenix_API docs so one repo has full API doc. |
|
||||
| 4.4 | **API versioning strategy** | Sankofa | Low | Document in Sankofa docs/api/API_VERSIONING.md; align /api/v1/ with strategy. |
|
||||
|
||||
---
|
||||
|
||||
## 5. Testing and Quality
|
||||
|
||||
| # | Task | Owner | Priority | Notes |
|
||||
|---|------|--------|----------|--------|
|
||||
| 5.1 | **Integration tests for REST railing routes** | Sankofa | Medium | Test GET /api/v1/infra/nodes, /ve/vms, /health/summary and tenant me routes (with mock or real PHOENIX_RAILING_URL). |
|
||||
| 5.2 | **E2E: Portal → Phoenix API → Railing** | Sankofa | Medium | After Portal calls are implemented, add E2E that hits Sankofa API and (optionally) railing. |
|
||||
|
||||
---
|
||||
|
||||
## 6. Portal Implementation (Depends on API)
|
||||
|
||||
| # | Task | Owner | Priority | Notes |
|
||||
|---|------|--------|----------|--------|
|
||||
| 6.1 | **Portal: Infrastructure overview** — call GET /api/v1/infra/nodes, /api/v1/infra/storage | Sankofa | High | See docs/phoenix/PORTAL_RAILING_WIRING.md. |
|
||||
| 6.2 | **Portal: VM/CT list and actions** — call GET/POST /api/v1/ve/vms/* | Sankofa | High | List, status, start/stop/reboot. |
|
||||
| 6.3 | **Portal: Health/dashboards** — call GET /api/v1/health/summary, /alerts, /metrics | Sankofa | High | Dashboards and alerts. |
|
||||
| 6.4 | **Portal: Keycloak token for API** | Sankofa | High | Server-side or BFF uses token for Phoenix API calls; token includes tenant when applicable. |
|
||||
|
||||
---
|
||||
|
||||
## 7. Optional / Later
|
||||
|
||||
| # | Task | Owner | Notes |
|
||||
|---|------|--------|--------|
|
||||
| 7.1 | Rate limiting per tenant (beyond global) | Sankofa | rateLimitMiddleware exists; per-tenant limits if needed. |
|
||||
| 7.2 | Swagger UI in phoenix-deploy-api at /api-docs | Proxmox | Add swagger-ui-express; serve openapi.yaml. |
|
||||
| 7.3 | Alert webhook (alert fired → POST to partner URL) | Proxmox | Beyond deploy webhook; optional. |
|
||||
|
||||
---
|
||||
|
||||
## Summary Checklist
|
||||
|
||||
**Must-do to “complete” the API for Sankofa:**
|
||||
|
||||
- [x] **1.1** API key store (DB: api_keys + verifyApiKey; X-API-Key in tenant-auth for /api/v1/*)
|
||||
- [ ] **2.1** Commit and push Sankofa API changes to Gitea
|
||||
- [ ] **2.2** Re-sync Phoenix_API Gitea repo from api/ subtree
|
||||
- [ ] **3.1** Set PHOENIX_RAILING_URL in Sankofa API
|
||||
- [ ] **3.3** Configure Proxmox (and optional Prometheus) env for phoenix-deploy-api
|
||||
|
||||
**Should-do:**
|
||||
|
||||
- [ ] **2.3** Commit and push phoenix-deploy-api (openapi, docs, server, /api-docs) to Gitea
|
||||
- [x] **4.1** GraphQL schema export + interactive docs
|
||||
- [x] **4.2–4.4** OpenAPI GraphQL, api/docs, versioning doc
|
||||
- [x] **5.1** Integration tests for railing (phoenix-railing.test.ts)
|
||||
- [x] **7.2** Swagger UI at /api-docs in phoenix-deploy-api
|
||||
- [ ] **6.1–6.4** Portal wiring to Infra/VE/Health APIs and Keycloak
|
||||
|
||||
**Optional:**
|
||||
|
||||
- [ ] 1.2 Site24x7 API keys (after 1.1)
|
||||
- [ ] 4.2, 4.3, 4.4 API docs enhancements
|
||||
- [ ] 5.1, 5.2 Tests
|
||||
- [ ] 7.x Optional items
|
||||
|
||||
---
|
||||
|
||||
## Quick Commands
|
||||
|
||||
**Sankofa — commit and push to Sankofa_Phoenix:**
|
||||
```bash
|
||||
cd /home/intlc/projects/Sankofa
|
||||
git add api/
|
||||
git status # review
|
||||
git commit -m "API: phoenix-railing proxy, tenant me routes, sovereign-stack, migrations"
|
||||
git push sankofa_phoenix main
|
||||
```
|
||||
|
||||
**Sankofa — re-sync Phoenix_API repo:**
|
||||
```bash
|
||||
cd /home/intlc/projects/Sankofa
|
||||
git subtree split -P api -b phoenix-api
|
||||
# Use GITEA_TOKEN from proxmox .env:
|
||||
git push https://oauth2:${GITEA_TOKEN}@gitea.d-bis.org/Sankofa_Phoenix/Phoenix_API.git phoenix-api:main
|
||||
git branch -D phoenix-api
|
||||
```
|
||||
|
||||
**Proxmox — commit and push phoenix-deploy-api to Gitea:**
|
||||
```bash
|
||||
cd /home/intlc/projects/proxmox
|
||||
git add phoenix-deploy-api/openapi.yaml phoenix-deploy-api/docs/ phoenix-deploy-api/README.md phoenix-deploy-api/server.js
|
||||
git commit -m "Phoenix Deploy API: OpenAPI spec, Swagger UI doc, railing and health routes"
|
||||
git push gitea main
|
||||
```
|
||||
Reference in New Issue
Block a user