Phoenix Deploy API: alert webhook, .env.example, Site24x7 and E2E docs

- PHOENIX_ALERT_WEBHOOK_URL: POST on alerts when firing
- .env.example: PROXMOX_*, PROMETHEUS_*, webhooks, partner keys
- PHOENIX_SITE24X7_API_KEYS.md: how to issue API keys for Site24x7
- PHOENIX_E2E_PORTAL_API_RAILING.md: E2E test steps and references

Made-with: Cursor

docs/02-architecture/PHOENIX_E2E_PORTAL_API_RAILING.md

@@ -0,0 +1,27 @@
+# E2E: Portal → Phoenix API → Railing
+
+**Purpose:** How to run and extend E2E tests for the flow: Portal (browser) → Sankofa Phoenix API → Phoenix Deploy API (railing).
+
+## Flow
+
+1. User signs in to Portal (NextAuth / Keycloak).
+2. Portal calls Sankofa API with `Authorization: Bearer <accessToken>` (or session cookie).
+3. Sankofa API proxies `/api/v1/infra/*`, `/api/v1/ve/*`, `/api/v1/health/*` to `PHOENIX_RAILING_URL` when set.
+4. Tenant-scoped routes (`/api/v1/tenants/me/resources`, `/api/v1/tenants/me/health`) use JWT or X-API-Key tenant context.
+
+## Manual E2E
+
+1. Start Phoenix Deploy API: `cd phoenix-deploy-api && npm start` (optional: set PROXMOX_* for live data).
+2. Start Sankofa API: set `PHOENIX_RAILING_URL=http://localhost:4001`, then `npm run dev`.
+3. Start Portal: set `NEXT_PUBLIC_GRAPHQL_ENDPOINT=http://localhost:4000/graphql` (or API URL), then `npm run dev`.
+4. Sign in, open Infrastructure page (`/infrastructure`), verify nodes/storage load; open Dashboard and verify Phoenix Health tile; open VMs and verify list (if Crossplane or railing VMs are used).
+
+## Automated E2E (optional)
+
+- **Playwright/Cypress:** Add tests that sign in, navigate to `/infrastructure`, `/vms`, dashboard, and assert presence of data or “Loading”/error states.
+- **API-only:** Use Sankofa API integration tests: start server with test config, `fetch('/api/v1/health/summary', { headers: { Authorization: 'Bearer <test-jwt>' } })` and assert 200 and body shape. See `api/src/__tests__/integration/phoenix-railing.test.ts` for tenant-me routes.
+
+## References
+
+- [PORTAL_RAILING_WIRING.md](../../Sankofa/docs/phoenix/PORTAL_RAILING_WIRING.md) (in Sankofa repo)
+- [PHOENIX_API_RAILING_SPEC.md](PHOENIX_API_RAILING_SPEC.md)

docs/04-configuration/PHOENIX_SITE24X7_API_KEYS.md

@@ -0,0 +1,40 @@
+# Site24x7 API Keys for Phoenix API
+
+**Purpose:** Issue Phoenix API keys for Site24x7 (and similar) users so they can call `/api/v1/*` (Infra, VE, Health) with `X-API-Key` or `Authorization: Bearer <key>`.
+
+## Prerequisites
+
+- API key store is in place (Sankofa API: `api_keys` table + migration 026).
+- Users or service accounts exist in Gitea (e.g. Site24x7 team in Sankofa_Phoenix org).
+
+## Steps
+
+1. **Create API key in Sankofa API**
+   - Use GraphQL mutation `createApiKey` (or future admin REST endpoint) with:
+     - `name`: e.g. `Site24x7-monitor`
+     - `permissions`: `["read"]` for read-only (Infra, VE, Health); `["read","write"]` if VM lifecycle is allowed.
+   - Or insert into `api_keys` (key_hash = SHA256 of the secret key, key_prefix = first 12 chars).
+   - Return the **plain key** once to the operator; store only the hash.
+
+2. **Assign tenant (optional)**
+   - If the key should be tenant-scoped, set `tenant_id` on the `api_keys` row so `/api/v1/tenants/me/*` returns that tenant’s data.
+
+3. **Configure Site24x7**
+   - In Site24x7 monitor config, set:
+     - **URL:** `https://api.sankofa.nexus/api/v1/health/summary` (or your Phoenix API base).
+     - **Header:** `X-API-Key: <key>` or `Authorization: Bearer <key>`.
+
+4. **Phoenix Deploy API (direct)**  
+   If Site24x7 hits phoenix-deploy-api directly (not via Sankofa API), add the same key to `PHOENIX_PARTNER_KEYS` in phoenix-deploy-api `.env`.
+
+## Gitea team → API keys
+
+For each Gitea user in the Site24x7 team who needs API access:
+
+- Ensure the user exists in Sankofa (Keycloak/users table) if using JWT; or create an API key bound to a service user and share the key securely.
+- Prefer one key per service (e.g. one key for Site24x7) rather than per user, unless each user has a distinct integration.
+
+## References
+
+- [PHOENIX_PARTNER_INTEGRATION_SITE24X7_MANAGEENGINE.md](PHOENIX_PARTNER_INTEGRATION_SITE24X7_MANAGEENGINE.md)
+- Sankofa API: `api_keys` table, `verifyApiKey()`, X-API-Key in tenant-auth for `/api/v1/*`.