proxmox/docs/04-configuration/PHOENIX_DEPLOY_API_GITEA_INTEGRATION.md

Phoenix Deploy API — Gitea Integration

Last Updated: 2026-04-22
Status: Active Documentation

---

Operator handoff: 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/) 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):

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 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):

# 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):

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):

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:

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), with CT 5700 on this node, run one line (backs up /opt/phoenix-deploy-api/.env first, prints the new token, restarts the service):

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:

{
  "repo": "d-bis/proxmox",
  "branch": "main",
  "sha": "abc123def",
  "target": "default"
}

Deploy target discovery

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. On systemd install, install-systemd.sh copies it next to server.js; override with PUBLIC_SECTOR_MANIFEST_PATH or PHOENIX_REPO_ROOT.

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.