# Phoenix Deploy API — Gitea Integration

**Last Updated:** 2026-04-20  
**Status:** Active Documentation

---

## 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.

## 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/`

## 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.