Blame · Line-by-line history
DEPLOY.md
Each line is annotated with the commit that last touched it. Click any SHA to jump to that commit and see the surrounding change.
| 988380a | 1 | # Deploying Gluecron |
| 8ade77b | 2 | |
| 90fa787 | 3 | Gluecron is a standalone product. It runs anywhere Bun runs. The repo ships a `fly.toml` for Fly.io as the documented primary target, and a `Dockerfile` for any other container host. |
| 3644238 | 4 | |
| 988380a | 5 | --- |
| 3644238 | 6 | |
| 988380a | 7 | ## 1. Prerequisites |
| 3644238 | 8 | |
| 988380a | 9 | 1. **Neon Postgres** — create a project at https://neon.tech and copy the pooled connection string. This becomes `DATABASE_URL`. |
| 90fa787 | 10 | 2. **Fly.io account** (or any Docker-compatible host) — `flyctl` installed locally if you're using Fly. |
| 988380a | 11 | 3. **(Recommended) Anthropic API key** — https://console.anthropic.com. Everything AI-flavoured degrades to safe fallbacks without it, but you'll want this for the differentiator features. |
| 3644238 | 12 | |
| 988380a | 13 | --- |
| 8ade77b | 14 | |
| 90fa787 | 15 | ## 2. Deploy to Fly.io |
| 8ade77b | 16 | |
| 90fa787 | 17 | The repo includes a ready `fly.toml`. First-time setup: |
| 8ade77b | 18 | |
| 90fa787 | 19 | ```bash |
| 20 | fly launch # adopts the existing fly.toml; pick an app name and region | |
| 21 | fly deploy # builds via the in-repo Dockerfile and releases | |
| 22 | ``` | |
| 23 | ||
| 24 | The shipped `fly.toml` already wires up: | |
| 25 | ||
| 26 | - **Release command:** `bun run db:migrate` (runs before each deploy cuts over) | |
| 27 | - **Persistent volume:** `gluecron_repos` mounted at `/app/repos` (bare git repos live on disk) | |
| 28 | - **HTTP service** on port 3000 with forced HTTPS | |
| 8ade77b | 29 | |
| 90fa787 | 30 | Set secrets before the first deploy: |
| 8ade77b | 31 | |
| 90fa787 | 32 | ```bash |
| 33 | fly secrets set DATABASE_URL="..." APP_BASE_URL="https://your-app.fly.dev" ANTHROPIC_API_KEY="..." | |
| 34 | ``` | |
| 35 | ||
| 36 | Route a custom domain via `fly certs add your-domain.com` if you want something other than `*.fly.dev`. | |
| 37 | ||
| 38 | ### Other Docker hosts | |
| 39 | ||
| 40 | Any platform that runs the in-repo `Dockerfile` works. Required wiring: | |
| 41 | ||
| 42 | - **Build:** `docker build .` | |
| 43 | - **Release (pre-start):** `bun run db:migrate` | |
| 44 | - **Start:** `bun run src/index.ts` | |
| 45 | - **Port:** `3000` | |
| 46 | - **Persistent volume:** mount the path set by `GIT_REPOS_PATH` (default `/app/repos`) | |
| 8ade77b | 47 | |
| 988380a | 48 | --- |
| 8ade77b | 49 | |
| 988380a | 50 | ## 3. Environment variables |
| 8ade77b | 51 | |
| 988380a | 52 | Full reference is in [`.env.example`](./.env.example); cross-reference BUILD_BIBLE §5.2 for anything not listed here. |
| 8ade77b | 53 | |
| 988380a | 54 | ### Required |
| 55 | | Variable | Purpose | | |
| 56 | |---|---| | |
| 57 | | `DATABASE_URL` | Neon Postgres connection string (pooled). | | |
| 58 | | `GIT_REPOS_PATH` | Where bare repos live on disk (e.g. `/data/repos`). | | |
| 59 | | `PORT` | HTTP port. Default `3000`. | | |
| 60 | | `APP_BASE_URL` | Canonical public URL, used when composing outbound emails and webhooks. | | |
| 8ade77b | 61 | |
| 988380a | 62 | ### Strongly recommended |
| 63 | | Variable | Purpose | | |
| 64 | |---|---| | |
| 65 | | `ANTHROPIC_API_KEY` | Unlocks AI review, triage, chat, incident responder, auto-repair, completions. | | |
| 66 | | `EMAIL_PROVIDER` | `log` (default, writes to stderr) or `resend` (production). | | |
| 67 | | `EMAIL_FROM` | Sender identity on outbound mail. | | |
| 68 | | `RESEND_API_KEY` | Required when `EMAIL_PROVIDER=resend`. | | |
| 69 | | `VOYAGE_API_KEY` | Upgrades semantic search to Voyage `voyage-code-3` embeddings; without it, a deterministic hashing embedder is used. | | |
| 70 | ||
| 90fa787 | 71 | ### Integrations (all optional) |
| 988380a | 72 | | Variable | Purpose | |
| 73 | |---|---| | |
| 90fa787 | 74 | | `GATETEST_URL` | Outbound push webhook to the GateTest third-party security scanner. Default `https://gatetest.ai/api/events/push`. | |
| 988380a | 75 | | `GATETEST_API_KEY` | Bearer sent on outbound GateTest posts. | |
| 76 | | `GATETEST_CALLBACK_SECRET` | Inbound bearer GateTest must present on result callbacks. See `GATETEST_HOOK.md`. | | |
| 77 | | `GATETEST_HMAC_SECRET` | HMAC secret for inbound GateTest callbacks (alternative to bearer). | | |
| 90fa787 | 78 | | `CRONTECH_DEPLOY_URL` | Optional outbound deploy webhook. When set, pushes to the default branch POST here. | |
| 79 | | `GLUECRON_WEBHOOK_SECRET` | Bearer sent on the outbound deploy webhook above. | | |
| 80 | | `CRONTECH_EVENT_TOKEN` | Bearer an external deploy service must present on `deploy.succeeded` / `deploy.failed` callbacks to `POST /api/events/deploy`. | | |
| 81 | | `CRONTECH_STATUS_URL` / `GLUECRON_STATUS_URL` / `GATETEST_STATUS_URL` | Third-party platform-status endpoints surfaced in the `/admin/platform` widget. | | |
| 8ade77b | 82 | |
| 988380a | 83 | ### Operational flags |
| 84 | | Variable | Purpose | | |
| 85 | |---|---| | |
| 86 | | `AUTOPILOT_DISABLED=1` | Opt out of the 5-minute autopilot ticker (mirror sync, merge-queue processing, weekly digests, advisory rescans). Default: enabled. | | |
| 87 | | `DEMO_SEED_ON_BOOT=1` | Idempotently create a `demo` user plus three public sample repos (`hello-python`, `todo-api`, `design-docs`) on server start. Safe to leave enabled — a second run is a near-instant no-op. Site admins can also trigger a reseed manually from `/admin`. | | |
| 88 | ||
| 534f04a | 89 | ### Web Push / PWA (Block M2) |
| 90 | | Variable | Purpose | | |
| 91 | |---|---| | |
| 92 | | `VAPID_PUBLIC_KEY` | Base64url-encoded uncompressed P-256 public key (65 bytes). Sent to browsers as the `applicationServerKey` for `pushManager.subscribe()`. **If unset, a fresh keypair is generated in-memory at first use and every restart invalidates all existing subscriptions — production must set this.** | | |
| 93 | | `VAPID_PRIVATE_KEY` | Base64url-encoded raw 32-byte private scalar paired with `VAPID_PUBLIC_KEY`. Used to ES256-sign the per-delivery JWT. Treat as a secret. | | |
| 94 | | `VAPID_SUBJECT` | `mailto:` or `https:` URL identifying the app, included in every VAPID JWT. Defaults to `mailto:ops@gluecron.com`. | | |
| 95 | ||
| 96 | To generate a fresh pair locally, run a one-off Bun snippet using Web Crypto's `subtle.generateKey({ name: "ECDSA", namedCurve: "P-256" }, true, ["sign", "verify"])` and base64url-encode the raw public key + the JWK private scalar (`d`). The boot log emits the generated public key on first push send when env vars are absent. | |
| 97 | ||
| 988380a | 98 | --- |
| 99 | ||
| 100 | ## 4. Database migrations | |
| 101 | ||
| 102 | Migrations are checked into `drizzle/` and run via: | |
| 8ade77b | 103 | |
| 104 | ```bash | |
| 988380a | 105 | bun run db:migrate |
| 8ade77b | 106 | ``` |
| 107 | ||
| 90fa787 | 108 | Hook this into your host's release phase so every deploy self-migrates. On Fly.io the in-repo `fly.toml` already wires this up via `[deploy].release_command`. First-time bootstrap: the release command will pick up `0000_init.sql` through the latest migration in order. |
| 8ade77b | 109 | |
| 988380a | 110 | --- |
| 8ade77b | 111 | |
| 988380a | 112 | ## 5. Post-deploy checklist |
| 8ade77b | 113 | |
| 988380a | 114 | Verify these in order after the first deploy: |
| 8ade77b | 115 | |
| 90fa787 | 116 | - [ ] **Release command ran successfully** — `bun run db:migrate` reported success in the release logs. |
| 988380a | 117 | - [ ] **`/healthz` is green** — returns `{"ok": true, ...}` with a 200. |
| 118 | - [ ] **`/readyz` is green** — returns `{"ok": true}`, confirming DB connectivity. | |
| 119 | - [ ] **`/metrics` responds** — basic process snapshot is emitted. | |
| 120 | - [ ] **First admin bootstrap** — register the first account at `/register`. Per `src/lib/admin.ts`, while `site_admins` is empty the **oldest user** is treated as site admin. Register the intended admin account first so the bootstrap rule applies; subsequent admins can then be granted from `/admin/users`. | |
| 121 | - [ ] **Smart HTTP works** — create a repo at `/new`, then `git clone https://<your-host>/<user>/<repo>.git` round-trips. | |
| 90fa787 | 122 | - [ ] **Push triggers the pipeline** — a `git push` fires the secret scanner, webhook fan-out, and (if configured) the outbound GateTest post (check `/:owner/:repo/gates` and `/:owner/:repo/settings/audit`). |
| 988380a | 123 | - [ ] **Custom domain TLS** — certificate issued and `APP_BASE_URL` reflects the canonical host. |
| 124 | - [ ] **Autopilot state** — if you want the background ticker off, confirm `AUTOPILOT_DISABLED=1` is set; otherwise expect mirror syncs and weekly digests to fire on schedule. | |
| 8ade77b | 125 | |
| 988380a | 126 | --- |
| 8ade77b | 127 | |
| 988380a | 128 | ## 6. Operations |
| 8ade77b | 129 | |
| 988380a | 130 | ### Logs |
| 90fa787 | 131 | Your host streams stdout/stderr from `bun run src/index.ts` (on Fly.io: `fly logs`). Every request carries an `X-Request-Id` header; grep logs by that ID when tracing a report. |
| 988380a | 132 | |
| 133 | ### Restarts | |
| 90fa787 | 134 | Trigger from your host's dashboard or CLI (on Fly.io: `fly apps restart`). Rate-limit counters are in-memory and reset on restart — that is intentional. |
| 988380a | 135 | |
| 136 | ### Rollbacks | |
| 90fa787 | 137 | Roll back via your host's release history (on Fly.io: `fly releases` + `fly deploy --image <previous>`). Database migrations are additive; rolling back the service does not roll back the schema. If a migration needs reverting, write a new forward-migration. |
| 988380a | 138 | |
| 139 | ### Backups | |
| 90fa787 | 140 | Neon handles PITR + branch snapshots — configure retention in the Neon console. The bare repos on the persistent volume must be backed up separately (filesystem snapshot of the mount at `GIT_REPOS_PATH`; on Fly.io, snapshot the `gluecron_repos` volume). See BUILD_BIBLE §2.6 for what still needs wiring on the observability side. |
| 988380a | 141 | |
| 142 | --- | |
| 8ade77b | 143 | |
| 988380a | 144 | ## 7. Graceful-degradation matrix |
| 8ade77b | 145 | |
| 988380a | 146 | | Missing secret | Effect | |
| 147 | |---|---| | |
| 148 | | `DATABASE_URL` | App boots, `/healthz` returns 200, any DB-backed route returns 500. Do not deploy without it. | | |
| 149 | | `ANTHROPIC_API_KEY` | AI review, chat, triage, incident, completions, explain, test-gen, merge resolver all return deterministic fallback strings. Site remains fully usable as a plain git host. | | |
| 150 | | `GATETEST_API_KEY` | Outbound GateTest integration silently skipped. Local secret scanner + gate runner still execute. | | |
| 151 | | `RESEND_API_KEY` (with `EMAIL_PROVIDER=resend`) | `sendEmail()` still never throws; emails are logged instead of delivered. | | |
| 152 | | `VOYAGE_API_KEY` | Semantic search falls back to the deterministic hashing embedder. Quality drops; feature still works. | | |
| 8ade77b | 153 | |
| 988380a | 154 | Every missing integration follows the same rule: **never break the primary request path**. See BUILD_BIBLE §4.9 for the full invariant list. |
| f764c07 | 155 | |
| 156 | --- | |
| 157 | ||
| 158 | ## Lightning-fast deploys (Block N1) | |
| 159 | ||
| 160 | Once PR #62 has landed and the release-command has applied migration 0040, the operator can flip a single repo into "auto-merge mode" with two scripts. From "feature description → live in ~6 minutes, zero clicks" goes from possible to the default. | |
| 161 | ||
| 162 | ### What it does | |
| 163 | ||
| 164 | When `branch_protection.enable_auto_merge=true` on the matching rule, the K3 autopilot sweep (`auto-merge-sweep`, fires every 5 minutes) will auto-merge any PR that: | |
| 165 | ||
| 166 | - Targets a branch matching the rule's `pattern` | |
| 167 | - Is not a draft | |
| 168 | - Passes every gate the manual-merge path enforces (green gates, AI approval, required checks) | |
| 169 | - Is not flagged as `critical` by the M3 PR risk scorer | |
| 170 | ||
| 171 | The merge is performed by the autopilot, not by any human click. Default-deny: this only fires on rules where the operator has explicitly opted in. | |
| 172 | ||
| 173 | ### Step 1 — Readiness check | |
| 174 | ||
| 175 | Run the preflight to make sure the box is in a state where opting in will actually do something useful: | |
| 176 | ||
| 177 | ```bash | |
| 178 | # Fly.io | |
| 179 | fly ssh console -C "bun run /opt/gluecron/scripts/check-auto-merge-readiness.ts" | |
| 180 | ||
| 181 | # Hetzner (matches scripts/bootstrap-hetzner.sh) | |
| 182 | ssh root@gluecron.com "cd /opt/gluecron && bun run scripts/check-auto-merge-readiness.ts" | |
| 183 | ``` | |
| 184 | ||
| 185 | The check verifies: | |
| 186 | - Migration 0040 has been applied (`branch_protection.enable_auto_merge` column exists) | |
| 187 | - `ANTHROPIC_API_KEY` is set (otherwise the AI approval gate blocks every candidate) | |
| 188 | - The autopilot is running (`AUTOPILOT_DISABLED != 1`) | |
| 189 | - The K3 `auto-merge-sweep` task is in `defaultTasks()` | |
| 190 | ||
| 191 | Exit code 0 if all green; 1 if any check fails. Fix any red lines before continuing. | |
| 192 | ||
| 193 | ### Step 2 — Flip the switch for a single repo | |
| 194 | ||
| 195 | ```bash | |
| 196 | # Fly.io | |
| 197 | fly ssh console -C "bun run /opt/gluecron/scripts/enable-auto-merge.ts ccantynz/Gluecron.com" | |
| 198 | ||
| 199 | # Hetzner | |
| 200 | ssh root@gluecron.com "cd /opt/gluecron && bun run scripts/enable-auto-merge.ts ccantynz/Gluecron.com" | |
| 201 | ``` | |
| 202 | ||
| 203 | By default this targets the `main` branch. Pass a second arg to target a different pattern, e.g. `release/*`: | |
| 204 | ||
| 205 | ```bash | |
| 206 | bun run scripts/enable-auto-merge.ts ccantynz/Gluecron.com release/* | |
| 207 | ``` | |
| 208 | ||
| 209 | The script is idempotent: | |
| 210 | - If a `branch_protection` row already exists for the (repo, pattern), it flips `enable_auto_merge=true` and preserves every other field. | |
| 211 | - If no row exists, it inserts a fresh one with the documented safety defaults (`require_green_gates=true`, `require_ai_approval=true`, `require_human_review=false`, `required_approvals=0`). | |
| 212 | - Running it twice in a row produces a "no-op" — no duplicate audit entry. | |
| 213 | ||
| 214 | It prints a before / after diff so you see exactly what changed, and writes an `auto_merge.enabled_on_main` row to `audit_log` for traceability. | |
| 215 | ||
| 216 | Within 5 minutes (the autopilot sweep cadence), any qualifying PR on that branch will auto-merge with zero human clicks. | |
| 217 | ||
| 218 | ### Revert | |
| 219 | ||
| 220 | To turn auto-merge back off: | |
| 221 | ||
| 222 | ```bash | |
| 223 | bun run scripts/enable-auto-merge.ts ccantynz/Gluecron.com --off | |
| 224 | ``` | |
| 225 | ||
| 226 | Or manually: `UPDATE branch_protection SET enable_auto_merge = false WHERE repository_id = ... AND pattern = 'main';`. The autopilot sweep is default-deny — it will stop firing the moment the column flips back to `false`. | |
| 227 | ||
| 228 | ### Don'ts | |
| 229 | ||
| 230 | - Do not run `enable-auto-merge.ts` without first running the readiness check. The AI approval gate silently fails closed when `ANTHROPIC_API_KEY` is missing, and you'll spend half an hour wondering why nothing auto-merges. | |
| 231 | - The script intentionally does NOT auto-discover repos and flip them all. Explicit per-repo opt-in is the whole point — the operator decides which repos go on autopilot. |