2026-10-27 00:31:12 -05:00
1 changed files with 164 additions and 0 deletions
@@ -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/<name>/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": "<id or name>", "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": "<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.