151 lines
6.5 KiB
Markdown
151 lines
6.5 KiB
Markdown
# Phoenix Deploy API — Gitea Integration
|
||
|
||
**Last Updated:** 2026-04-22
|
||
**Status:** Active Documentation
|
||
|
||
---
|
||
|
||
**Operator handoff:** [PHOENIX_SANKOFA_OPERATOR_HANDOFF.md](PHOENIX_SANKOFA_OPERATOR_HANDOFF.md) — live CT locations, secrets split, rotate/reload/verify commands, and current verified scope.
|
||
|
||
## Overview
|
||
|
||
The Phoenix Deploy API ([phoenix-deploy-api/](../../phoenix-deploy-api/)) receives Gitea webhooks and provides a deploy endpoint for triggering Phoenix deployments from Gitea Actions or external tools.
|
||
|
||
## Architecture
|
||
|
||
```
|
||
Gitea (push/tag) → Webhook / Action → Phoenix Deploy API → deploy target command
|
||
↓
|
||
health check + Gitea commit status
|
||
```
|
||
|
||
## Setup
|
||
|
||
### 1. Deploy Phoenix Deploy API
|
||
|
||
Run the service on a host reachable from Gitea (e.g. dev-vm 5700 or Phoenix API host):
|
||
|
||
```bash
|
||
cd phoenix-deploy-api
|
||
npm install
|
||
GITEA_TOKEN=<token> PHOENIX_DEPLOY_SECRET=<secret> npm start
|
||
```
|
||
|
||
Or as systemd service on dev-vm.
|
||
|
||
**Bootstrap helper (recommended):**
|
||
|
||
```bash
|
||
bash scripts/dev-vm/bootstrap-phoenix-cicd.sh --repo d-bis/proxmox
|
||
```
|
||
|
||
This runs validation, deploys `phoenix-deploy-api`, and smoke-checks `/health` and `/api/deploy-targets`.
|
||
|
||
### 2. Gitea Webhook Configuration
|
||
|
||
**Via script (for repos that are not already deploying through Gitea Actions):**
|
||
|
||
```bash
|
||
# Ensure Phoenix Deploy API is running (e.g. on dev-vm at 192.168.11.59:4001)
|
||
GITEA_TOKEN=xxx PHOENIX_WEBHOOK_URL=http://192.168.11.59:4001/webhook/gitea PHOENIX_DEPLOY_SECRET=shared-secret bash scripts/dev-vm/add-gitea-webhook-phoenix.sh some/repo
|
||
```
|
||
|
||
Set `PHOENIX_WEBHOOK_DEPLOY_ENABLED=1` on the deploy service host if you want webhook events to execute the default target. Leave it unset or `0` when the repo already deploys through Gitea Actions.
|
||
|
||
**Manual (per-repository):**
|
||
|
||
1. Gitea → d-bis/proxmox → Settings → Webhooks → Add Webhook
|
||
2. **URL:** `https://<phoenix-deploy-host>/webhook/gitea`
|
||
3. **Content type:** application/json
|
||
4. **Secret:** Optional; set `PHOENIX_DEPLOY_SECRET` to match
|
||
5. **Triggers:** Push events, Tag creation
|
||
|
||
**Organization-level webhook** (if supported): Configure once for all repos in d-bis.
|
||
|
||
### 3. Gitea Token
|
||
|
||
Create a token at https://gitea.d-bis.org/user/settings/applications with scope `repo` (or `repo:status`) for commit status updates.
|
||
|
||
### 4. Deploy token (`PHOENIX_DEPLOY_TOKEN`)
|
||
|
||
Repo and CI use **`PHOENIX_DEPLOY_TOKEN`** in `.env` for `Authorization: Bearer` on `POST /api/deploy`. That value must match **`PHOENIX_DEPLOY_SECRET`** in the service env on the Phoenix Deploy API host (e.g. dev VM `192.168.11.59` / VMID `5700`).
|
||
|
||
On a machine that can **SSH to root** on the API host, read the secret from the same file `phoenix-deploy-api.service` loads (default below):
|
||
|
||
```bash
|
||
ssh root@192.168.11.59 "awk -F= '/^PHOENIX_DEPLOY_SECRET=/{sub(/^[^=]*=/,\"\"); gsub(/^[\"'\'']+|[\"'\'']+$/,\"\"); print; exit}' /opt/phoenix-deploy-api/.env"
|
||
```
|
||
|
||
Confirm the env file path in the unit first (optional):
|
||
|
||
```bash
|
||
ssh root@192.168.11.59 "systemctl cat phoenix-deploy-api | rg EnvironmentFile"
|
||
```
|
||
|
||
If you have **Proxmox root** on the node that runs CT `5700` but **not** the guest’s root password, use `pct exec` instead of SSH to `.59` — see `scripts/lib/load-project-env.sh` (`get_host_for_vmid` → `5700` → `r630-04` by default). Example:
|
||
|
||
```bash
|
||
pct exec 5700 -- sh -c "awk -F= '/^PHOENIX_DEPLOY_SECRET=/{sub(/^[^=]*=/,\"\"); gsub(/^[\"'\'']+|[\"'\'']+$/,\"\"); print; exit}' /opt/phoenix-deploy-api/.env"
|
||
```
|
||
|
||
#### Rotate an empty (or new) `PHOENIX_DEPLOY_SECRET` on the dev VM
|
||
|
||
If `PHOENIX_DEPLOY_SECRET=` is empty, deploy API auth and webhooks that expect a shared secret will not work. From **Proxmox `r630-04`** (default: `root@192.168.11.14` — `PROXMOX_HOST_R630_04` in [`config/ip-addresses.conf`](../../config/ip-addresses.conf)), with CT **5700** on this node, run **one line** (backs up `/opt/phoenix-deploy-api/.env` first, prints the new token, restarts the service):
|
||
|
||
```bash
|
||
SECRET=$(openssl rand -hex 32) && echo "PHOENIX_DEPLOY_TOKEN: $SECRET" && pct exec 5700 -- sh -c 'f=/opt/phoenix-deploy-api/.env; test -f "$f" && cp -a "$f" "$f.bak.$(date +%s)"' && pct exec 5700 -- env "SECRET=$SECRET" sh -c 'grep -v ^PHOENIX_DEPLOY_SECRET= /opt/phoenix-deploy-api/.env > /tmp/pde.env && echo PHOENIX_DEPLOY_SECRET=$SECRET >> /tmp/pde.env && mv /tmp/pde.env /opt/phoenix-deploy-api/.env' && pct exec 5700 -- systemctl restart phoenix-deploy-api
|
||
```
|
||
|
||
If you are not on `r630-04` yet: `ssh root@192.168.11.14` (or the host that actually runs 5700), then paste the line above. Copy **`PHOENIX_DEPLOY_TOKEN: …`** into repo/CI `PHOENIX_DEPLOY_TOKEN` and any Gitea webhook or tool that was using the same secret. Optional: `pct exec 5700 -- sh -c 'set -a; . /opt/phoenix-deploy-api/.env; echo "len=${#PHOENIX_DEPLOY_SECRET}"'` (expect `64` for a `openssl rand -hex 32` value).
|
||
|
||
## Deploy Endpoint
|
||
|
||
`POST /api/deploy`
|
||
|
||
**Headers:** `Authorization: Bearer <PHOENIX_DEPLOY_SECRET>`
|
||
|
||
**Body:**
|
||
```json
|
||
{
|
||
"repo": "d-bis/proxmox",
|
||
"branch": "main",
|
||
"sha": "abc123def",
|
||
"target": "default"
|
||
}
|
||
```
|
||
|
||
## Deploy target discovery
|
||
|
||
```bash
|
||
curl -sS http://127.0.0.1:4001/api/deploy-targets | jq .
|
||
```
|
||
|
||
Targets are loaded from `phoenix-deploy-api/deploy-targets.json`.
|
||
|
||
Current repo-shipped targets include:
|
||
|
||
- `default` for `d-bis/proxmox` → publish `phoenix-deploy-api` to VMID `5700`
|
||
- `portal-live` for `d-bis/proxmox` → run `scripts/deployment/sync-sankofa-portal-7801.sh` and verify `http://192.168.11.51:3000/`
|
||
- `explorer-live` for `d-bis/explorer-monorepo` → sync staged workspace and redeploy the live explorer stack on VMID `5000`
|
||
|
||
## Public-sector program manifest (runtime)
|
||
|
||
The API serves the repo manifest at **`GET /api/v1/public-sector/programs`** (no API key). Source file: [`config/public-sector-program-manifest.json`](../../config/public-sector-program-manifest.json). On systemd install, `install-systemd.sh` copies it next to `server.js`; override with `PUBLIC_SECTOR_MANIFEST_PATH` or `PHOENIX_REPO_ROOT`.
|
||
|
||
```bash
|
||
curl -sS http://127.0.0.1:4001/api/v1/public-sector/programs | jq '.programs[].id'
|
||
```
|
||
|
||
## Status
|
||
|
||
- Real deploy target execution is implemented.
|
||
- Target health checks are supported.
|
||
- Gitea commit status is updated from the deploy service.
|
||
- Webhook helper supports the shared secret, and webhook deploy execution is opt-in via `PHOENIX_WEBHOOK_DEPLOY_ENABLED=1`.
|
||
|
||
## Next Steps
|
||
|
||
- Add a Phoenix API target for `7800` or `8600`.
|
||
- Integrate into Sankofa Phoenix API (VMID 8600) if you want a single control plane.
|
||
- Add NPMplus proxy for phoenix-deploy if exposed publicly.
|