From f1489ba8a842ed73c60258abdfc2a35539ba58c3 Mon Sep 17 00:00:00 2001 From: Jonathan Branan Date: Mon, 26 Oct 2026 23:31:04 -0500 Subject: [PATCH] docs: plan for automatic Komodo deploys from Gitea Actions --- docs/komodo-deploy-plan.md | 164 +++++++++++++++++++++++++++++++++++++ 1 file changed, 164 insertions(+) create mode 100644 docs/komodo-deploy-plan.md diff --git a/docs/komodo-deploy-plan.md b/docs/komodo-deploy-plan.md new file mode 100644 index 0000000..6308226 --- /dev/null +++ b/docs/komodo-deploy-plan.md @@ -0,0 +1,164 @@ +# Plan: Auto-deploy qbit-maid to Komodo from Gitea Actions + +Status: **proposal** — no workflow changes made yet. +Branch: `dev-komodo-deploy` + +## Goal + +When a commit lands on `main` (or a `dev*` branch), the image is built and pushed +to `git.jonb.io/jblu/qbit-maid`, and then the matching Komodo resource is +redeployed automatically — with no manual click in the Komodo UI. + +## Current state + +Two Gitea Actions workflows exist, both build-and-push only: + +| File | Trigger | Tag pushed | +|---|---|---| +| `.gitea/workflows/docker.yml` | push to `main` | `git.jonb.io/jblu/qbit-maid:latest` | +| `.gitea/workflows/docker-dev.yml` | push to `dev*` | `git.jonb.io/jblu/qbit-maid:dev` | + +Neither workflow talks to Komodo. There are currently **no Komodo references +anywhere in the repo**, so the Komodo side (stack/deployment resource, registry +credentials) is assumed to be configured out-of-band in the Komodo UI. + +## Design options + +| # | Approach | Ordering | CI change | Notes | +|---|---|---|---|---| +| A | **Gitea Actions step calls Komodo API** (`POST /execute/DeployStack`) | ✅ deploy strictly after image push | small | Needs API key/secret as Gitea secrets; runner must reach Komodo | +| B | Gitea repo webhook → Komodo `/listener/github/stack//deploy` | ❌ fires on push, races the image build | none | Komodo may pull the *old* `:latest`; needs `KOMODO_WEBHOOK_SECRET` | +| C | Komodo **Build** resource builds from the Gitea repo, deploy attached | ✅ | removes CI build | Moves building off Gitea Actions; bigger change | +| D | Komodo **Auto Update** (poll registry for new `:latest` digest) | ⚠️ up to poll interval late | none | Zero-effort safety net, not "on push" | + +**Recommendation: A, with D enabled as a backstop.** + +A gives deterministic ordering — the deploy can only start once the push step has +succeeded. D costs nothing and catches any deploy that A misses (e.g. a manual +`docker push`, or a failed API call). + +B is the tempting "no code" option but it is genuinely racy: the webhook fires on +`git push`, which is *before* the image exists in the registry. Komodo would +redeploy the previous `:latest`. Only pick B if you also switch to C. + +## Implementation + +### 1. Komodo-side prerequisites (manual, in the Komodo UI) + +1. Confirm the resource type and name — a **Stack** (`DeployStack`) or a + **Deployment** (`Deploy`). The plan below assumes a Stack named `qbit-maid`. +2. Make sure the Komodo server can pull from `git.jonb.io`. Add the registry + credentials under **Settings → Docker Registries** (or the stack's + `docker_account`), otherwise the redeploy will fail on `docker pull`. +3. Create an API key: **Settings → API Keys → New**. Scope it to a user that has + **Execute** permission on the `qbit-maid` stack. Save the key + secret. +4. Optional backstop: set the stack's update mode to **Auto Update**. + +### 2. Gitea secrets / variables + +Repo → **Settings → Actions → Secrets**: + +| Name | Kind | Value | +|---|---|---| +| `KOMODO_URL` | secret | `https://komo.example.com` (no trailing slash) | +| `KOMODO_API_KEY` | secret | from step 1.3 | +| `KOMODO_API_SECRET` | secret | from step 1.3 | +| `KOMODO_STACK` | variable | `qbit-maid` | + +`KOMODO_STACK` is a *variable*, not a secret — it is not sensitive and being able +to see it in the UI makes the workflow easier to read. + +### 3. Workflow change + +Append one step to each workflow, after `Build and push`. For `docker.yml`: + +```yaml + - + name: Trigger Komodo deploy + env: + KOMODO_URL: ${{ secrets.KOMODO_URL }} + KOMODO_API_KEY: ${{ secrets.KOMODO_API_KEY }} + KOMODO_API_SECRET: ${{ secrets.KOMODO_API_SECRET }} + KOMODO_STACK: ${{ vars.KOMODO_STACK }} + run: | + set -euo pipefail + response=$(curl -sS -w '\n%{http_code}' \ + -X POST "${KOMODO_URL}/execute/DeployStack" \ + -H 'Content-Type: application/json' \ + -H "x-api-key: ${KOMODO_API_KEY}" \ + -H "x-api-secret: ${KOMODO_API_SECRET}" \ + -d "{\"stack\": \"${KOMODO_STACK}\"}") + body=$(printf '%s' "$response" | sed '$d') + code=$(printf '%s' "$response" | tail -n1) + echo "Komodo responded HTTP ${code}" + echo "$body" + [ "$code" = "200" ] || exit 1 +``` + +`docker-dev.yml` is identical except `KOMODO_STACK` points at the dev stack +(e.g. `qbit-maid-dev`), so dev pushes never touch production. + +Notes on the API call: + +- Endpoint is `POST /execute/DeployStack` with the params object as the body. + The equivalent generic form is `POST /execute` with + `{"type": "DeployStack", "params": {"stack": "..."}}`. +- Auth headers are `x-api-key` and `x-api-secret`. +- `DeployStack` accepts `{"stack": "", "services": [], "stop_time": null}`. + Use the resource **id** rather than the name if the name is likely to change. +- **The call returns immediately** with an `Update` object; the deploy runs + asynchronously. A `200` means "queued", not "deployed". See step 4. + +### 4. Optional: wait for the deploy to actually finish + +If you want the workflow to go red when the deploy fails, poll +`POST /read/GetUpdate` with `{"update_id": ""}` until `status` is `Complete`, +then check `success`. Sketch: + +```bash +update_id=$(printf '%s' "$body" | python3 -c 'import sys,json; print(json.load(sys.stdin)["_id"]["$oid"])') +for _ in $(seq 1 60); do + sleep 5 + u=$(curl -sS -X POST "${KOMODO_URL}/read/GetUpdate" \ + -H 'Content-Type: application/json' \ + -H "x-api-key: ${KOMODO_API_KEY}" \ + -H "x-api-secret: ${KOMODO_API_SECRET}" \ + -d "{\"update_id\": \"${update_id}\"}") + status=$(printf '%s' "$u" | python3 -c 'import sys,json; print(json.load(sys.stdin)["status"])') + [ "$status" = "Complete" ] || continue + printf '%s' "$u" | python3 -c 'import sys,json; sys.exit(0 if json.load(sys.stdin)["success"] else 1)' +done +echo "Timed out waiting for deploy"; exit 1 +``` + +Recommendation: ship step 3 first, add step 4 only if you find yourself wanting +the CI signal. Polling adds up to 5 minutes of runner time per deploy. + +### 5. Testing + +1. Push `dev-komodo-deploy` — this matches `dev*`, so `docker-dev.yml` runs and + exercises the new step against the dev stack. Confirm the Komodo UI shows a + new `Deploy` update with operator = your API key's user. +2. Verify the running container actually picked up the new image + (`docker inspect` the image digest, or check the app's log line). +3. Merge to `main` and confirm the production stack redeploys. +4. Negative test: temporarily set `KOMODO_API_SECRET` to a bad value and confirm + the step fails loudly rather than silently passing. + +### 6. Rollback + +The change is additive — delete the `Trigger Komodo deploy` step and the +workflows are back to build-and-push only. No Komodo state is modified by the +workflow beyond triggering a deploy. + +## Open questions + +These need answers before the workflow change is written: + +1. **Stack or Deployment?** Determines `DeployStack` vs `Deploy`. +2. **Resource name(s)** for prod and dev. +3. **Is Komodo reachable from the Gitea runner?** If Komodo is on a private + network and the runner is not, option A is out and we fall back to B+C or D. +4. **Does Komodo already have registry credentials for `git.jonb.io`?** If not, + the first automated deploy will fail at pull time. +5. **Should dev deploys be automatic?** Some people prefer dev to stay manual.