CodeIssuesDiscussionsWikiPull RequestsProjectsCommitsActionsReleasesContributorsPulse● GatesSecuritySettingsDeploymentsPipelineInsightsAgents✨ Explain✨ Ask AI✨ Workspace✨ Spec✨ Tests▓ Debt Map✨ NL Search🏛 Archaeology
Blame · Line-by-line history
DEPLOYMENT_RUNBOOK.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.
| 7703650 | 1 | # Gluecron Deployment Runbook |
| 2 | ||
| 3 | Step-by-step guide for taking Gluecron from zero to running at | |
| 4 | `gluecron.com`. This runbook targets **infrastructure deployment** — | |
| 5 | Gluecron is deployed as free internal infrastructure for Craig's | |
| 6 | ecosystem, **not** as a paid product. | |
| 7 | ||
| 8 | --- | |
| 9 | ||
| 10 | ## What Gluecron is today | |
| 11 | ||
| 12 | - Git hosting (clone / push / fetch over Smart HTTP) | |
| 13 | - Web UI: issues, PRs, code browser, webhooks, SSH keys, OAuth, 2FA | |
| 14 | - Integrates with **GateTest** (scans on push) and **Crontech** | |
| 15 | (deploys on push to `main`) | |
| 16 | - **Not a paid product.** No Stripe. No tiers. Free infrastructure | |
| 17 | for Craig's ecosystem. | |
| 18 | - Pre-launch banner visible; public signups gated until owner review. | |
| 19 | ||
| 20 | --- | |
| 21 | ||
| 22 | ## Prerequisites | |
| 23 | ||
| 24 | - **Neon** account (managed Postgres) — <https://neon.tech> | |
| 25 | - **Fly.io** *or* **Railway** account (container deployment) | |
| 26 | - Domain `gluecron.com` in hand (registrar access for DNS records) | |
| 27 | - *(Optional)* **Resend** account for transactional email | |
| 28 | - *(Optional)* **Anthropic** API key for AI features (copilot, | |
| 29 | changelog summarisation, semantic search) | |
| 30 | - *(Optional)* **Voyage** API key for semantic code search embeddings | |
| 31 | - Local tooling: `bun`, `git`, `flyctl` or `railway` CLI | |
| 32 | ||
| 33 | --- | |
| 34 | ||
| 35 | ## Phase 1 — Provision Postgres (Neon) | |
| 36 | ||
| 37 | 1. Sign in to <https://neon.tech> and create a project named | |
| 38 | `gluecron`. | |
| 39 | 2. From the project dashboard, copy the pooled connection string. | |
| 40 | It looks like: | |
| 7a03066 | 41 | `postgresql://user:REDACTED@ep-xxx.eu-west-2.aws.neon.tech/neondb?sslmode=require` |
| 7703650 | 42 | 3. Save this value — it becomes `DATABASE_URL` in Phase 3. |
| 43 | 4. **Do NOT run migrations yet.** The container runs them as its | |
| 44 | release step (see `fly.toml` → `[deploy] release_command`). | |
| 45 | ||
| 46 | --- | |
| 47 | ||
| 48 | ## Phase 2 — Choose a platform | |
| 49 | ||
| 50 | Both platforms ship from the checked-in `Dockerfile`. Pick one. | |
| 51 | ||
| 52 | ### Option A — Fly.io (recommended; `fly.toml` already exists) | |
| 53 | ||
| 54 | `fly.toml` already configures the persistent `gluecron_repos` | |
| 55 | volume mounted at `/app/repos` and wires up migrations as the | |
| 56 | release command. | |
| 57 | ||
| 58 | ```bash | |
| 59 | fly auth login | |
| 60 | fly launch --no-deploy # accept existing fly.toml | |
| 61 | fly volumes create gluecron_repos --size 10 --region lhr | |
| 62 | fly secrets set \ | |
| b105d39 | 63 | DATABASE_URL="<DATABASE_URL_FROM_NEON>" \ |
| 7703650 | 64 | APP_BASE_URL="https://gluecron.com" \ |
| 65 | WEBAUTHN_RP_ID="gluecron.com" \ | |
| 66 | WEBAUTHN_ORIGIN="https://gluecron.com" \ | |
| 67 | WEBAUTHN_RP_NAME="gluecron" \ | |
| 68 | GATETEST_URL="https://gatetest.io/api/scan/run" \ | |
| 69 | GATETEST_API_KEY="..." \ | |
| 70 | GATETEST_CALLBACK_SECRET="..." \ | |
| 71 | GATETEST_HMAC_SECRET="..." \ | |
| 72 | CRONTECH_DEPLOY_URL="https://crontech.ai/api/hooks/gluecron/push" \ | |
| 73 | GLUECRON_WEBHOOK_SECRET="..." \ | |
| 74 | CRONTECH_EVENT_TOKEN="..." \ | |
| 75 | ANTHROPIC_API_KEY="..." \ | |
| 76 | EMAIL_PROVIDER="resend" \ | |
| 77 | RESEND_API_KEY="..." \ | |
| 78 | EMAIL_FROM="gluecron <no-reply@gluecron.com>" | |
| 79 | fly deploy | |
| 80 | ``` | |
| 81 | ||
| 82 | ### Option B — Railway (`railway.toml` already exists) | |
| 83 | ||
| 84 | 1. <https://railway.app> → new project → **Deploy from GitHub**. | |
| 85 | 2. Select the Gluecron repo; Railway picks up the `Dockerfile` | |
| 86 | via `railway.toml`. | |
| 87 | 3. Add a persistent volume mounted at `/app/repos` (Railway UI | |
| 88 | → service → Volumes). | |
| 89 | 4. Set all environment variables from Phase 3 in the Railway | |
| 90 | dashboard. | |
| 91 | 5. Railway will run `bun run db:migrate` as the release command | |
| 92 | on deploy. | |
| 93 | ||
| 94 | --- | |
| 95 | ||
| 96 | ## Phase 3 — Environment variables | |
| 97 | ||
| 98 | All variables that Gluecron reads from `process.env`, enumerated | |
| 99 | from `src/lib/config.ts` and direct `process.env.*` references in | |
| 100 | `src/`. | |
| 101 | ||
| 102 | ### Core runtime | |
| 103 | ||
| 104 | | Variable | Required? | Example | Notes | | |
| 105 | |---|---|---|---| | |
| b105d39 | 106 | | `DATABASE_URL` | **Yes** | `<DATABASE_URL_FROM_NEON>` | Neon pooled connection string. | |
| 7703650 | 107 | | `PORT` | No | `3000` | Preset in `fly.toml` / `railway.toml`. | |
| 108 | | `GIT_REPOS_PATH` | **Yes** in prod | `/app/repos` | Must be a persistent volume — this is where bare repos live. | | |
| 109 | | `NODE_ENV` | **Yes** in prod | `production` | Enables secure cookies and rate limiting. Preset in both configs. | | |
| 110 | | `APP_BASE_URL` | **Yes** | `https://gluecron.com` | Canonical base URL; used in outbound webhooks and email links. No trailing slash. | | |
| 111 | ||
| 112 | ### WebAuthn (passkeys / 2FA) | |
| 113 | ||
| 114 | | Variable | Required? | Example | Notes | | |
| 115 | |---|---|---|---| | |
| 116 | | `WEBAUTHN_RP_ID` | **Yes** | `gluecron.com` | Domain only, **no scheme, no port**. Passkeys are bound to this value; changing it invalidates existing keys. | | |
| 117 | | `WEBAUTHN_ORIGIN` | **Yes** | `https://gluecron.com` | Full origin including scheme. Must match what the browser sees. | | |
| 118 | | `WEBAUTHN_RP_NAME` | No | `gluecron` | Human-facing name shown by the browser. Default `gluecron`. | | |
| 119 | ||
| 120 | ### GateTest integration (scans on push) | |
| 121 | ||
| 122 | | Variable | Required? | Example | Notes | | |
| 123 | |---|---|---|---| | |
| a4e1564 | 124 | | `GATETEST_URL` | **Yes** (for integration) | `https://gatetest.ai/api/events/push` | Default `https://gatetest.ai/api/events/push`. | |
| 7703650 | 125 | | `GATETEST_API_KEY` | **Yes** | `gtk_...` | Outbound bearer token sent to GateTest. | |
| 126 | | `GATETEST_CALLBACK_SECRET` | **Yes** | *(random 32-byte hex)* | Bearer token GateTest uses when posting scan results back to Gluecron (`/hooks/gatetest`). | | |
| 127 | | `GATETEST_HMAC_SECRET` | **Yes** | *(random 32-byte hex)* | HMAC signing secret for GateTest → Gluecron callbacks. | | |
| 128 | ||
| 129 | ### Crontech integration (deploys on push to main) | |
| 130 | ||
| 131 | | Variable | Required? | Example | Notes | | |
| 132 | |---|---|---|---| | |
| 133 | | `CRONTECH_DEPLOY_URL` | **Yes** (for integration) | `https://crontech.ai/api/hooks/gluecron/push` | Outbound webhook target. | | |
| 134 | | `GLUECRON_WEBHOOK_SECRET` | **Yes** | *(random 32-byte hex)* | Bearer token on outbound Crontech deploy webhook. Empty → Crontech returns 401 and deploys fail. | | |
| 135 | | `CRONTECH_EVENT_TOKEN` | **Yes** | *(random 32-byte hex)* | Bearer token Crontech uses when posting deploy events back to Gluecron (`/api/deploy-events`). | | |
| 136 | ||
| 137 | ### Email (optional — `log` provider works without) | |
| 138 | ||
| 139 | | Variable | Required? | Example | Notes | | |
| 140 | |---|---|---|---| | |
| 141 | | `EMAIL_PROVIDER` | No | `resend` or `log` | Default `log` (writes to stderr). Set `resend` for real sending. | | |
| 142 | | `RESEND_API_KEY` | Only if `EMAIL_PROVIDER=resend` | `re_...` | Resend API key. | | |
| 143 | | `EMAIL_FROM` | No | `gluecron <no-reply@gluecron.com>` | From header. Default `gluecron <no-reply@gluecron.local>`. | | |
| 144 | ||
| 145 | ### AI / semantic search (optional) | |
| 146 | ||
| 147 | | Variable | Required? | Example | Notes | | |
| 148 | |---|---|---|---| | |
| 149 | | `ANTHROPIC_API_KEY` | No | `sk-ant-...` | Enables copilot, PR review, changelog summarisation. | | |
| 150 | | `VOYAGE_API_KEY` | No | `pa-...` | Enables Voyage embeddings for semantic code search. Falls back to a local model when absent. | | |
| 151 | ||
| 152 | **Total: 18 required/useful env vars** (plus `NODE_ENV`, `PORT`, | |
| 153 | `VOYAGE_API_KEY` as optional tuning). | |
| 154 | ||
| 155 | --- | |
| 156 | ||
| 157 | ## Phase 4 — Run migrations | |
| 158 | ||
| 159 | On both Fly.io and Railway, `bun run db:migrate` is the release | |
| 160 | command and runs automatically before traffic is routed to a new | |
| 161 | revision. If you need to run it manually: | |
| 162 | ||
| 163 | ```bash | |
| 164 | # Fly.io | |
| 165 | fly ssh console | |
| 166 | bun run db:migrate | |
| 167 | ||
| 168 | # Railway | |
| 169 | railway run bun run db:migrate | |
| 170 | ``` | |
| 171 | ||
| 172 | Verify the server starts cleanly — `bun run` should not error on | |
| 173 | boot. | |
| 174 | ||
| 175 | --- | |
| 176 | ||
| 177 | ## Phase 5 — DNS | |
| 178 | ||
| 179 | 1. Point `gluecron.com` at your platform: | |
| 180 | - **Fly.io**: `fly ips list` → create `A` and `AAAA` records | |
| 181 | to the IPv4/IPv6 shown. Alternatively | |
| 182 | `fly certs add gluecron.com` and follow the CNAME/ALIAS | |
| 183 | instructions. | |
| 184 | - **Railway**: add `gluecron.com` in the service → Settings → | |
| 185 | Domains. Railway prints the target `CNAME`. | |
| 186 | 2. Wait for Let's Encrypt to provision the certificate (usually | |
| 187 | under 5 minutes). Verify: | |
| 188 | ||
| 189 | ```bash | |
| 190 | curl -I https://gluecron.com/ | |
| 191 | ``` | |
| 192 | ||
| 193 | --- | |
| 194 | ||
| 195 | ## Phase 6 — Smoke test | |
| 196 | ||
| 197 | - [ ] Visit <https://gluecron.com/> — pre-launch banner is visible. | |
| 198 | - [ ] Register an account via email / OAuth. | |
| 199 | - [ ] Log in, visit **Settings → SSH keys**, add an SSH public key. | |
| 200 | - [ ] Create a repository from the UI. | |
| 201 | - [ ] `git clone https://gluecron.com/<you>/<repo>.git` — must | |
| 202 | succeed (this was the Smart HTTP bug fixed in commit | |
| 203 | `676be75`). | |
| 204 | - [ ] `git push` — verify it triggers a GateTest scan (if | |
| 205 | `GATETEST_URL` is set). | |
| 206 | - [ ] `git push` to `main` — verify it triggers a Crontech deploy | |
| 207 | (if `CRONTECH_DEPLOY_URL` is set). | |
| 208 | ||
| 209 | --- | |
| 210 | ||
| 211 | ## Phase 7 — Integration wires with GateTest & Crontech | |
| 212 | ||
| 213 | The three apps share secrets pairwise. Each secret value **must be | |
| 214 | identical on both sides of the wire**. | |
| 215 | ||
| 216 | | Secret | Set on Gluecron | Set on the other side | | |
| 217 | |---|---|---| | |
| 218 | | `GATETEST_API_KEY` | outbound auth to GateTest | GateTest validates this on its `/api/scan/run` endpoint | | |
| 219 | | `GATETEST_CALLBACK_SECRET` | validates callbacks from GateTest | GateTest sends as bearer on scan-result POSTs | | |
| 220 | | `GATETEST_HMAC_SECRET` | verifies signatures on GateTest callbacks | GateTest signs outbound callbacks with this | | |
| 221 | | `GLUECRON_WEBHOOK_SECRET` | outbound auth to Crontech | Crontech validates this on `/api/hooks/gluecron/push` | | |
| 222 | | `CRONTECH_EVENT_TOKEN` | validates deploy-event POSTs from Crontech | Crontech sends as bearer on `/api/deploy-events` | | |
| 223 | ||
| 224 | **Rule of thumb:** generate each secret once with | |
| 225 | `openssl rand -hex 32`, then copy the same value into the matching | |
| 226 | variable on both services. | |
| 227 | ||
| 228 | --- | |
| 229 | ||
| 230 | ## Phase 8 — Pre-launch → launch | |
| 231 | ||
| 232 | When Craig is ready to open signups: | |
| 233 | ||
| 234 | 1. Remove the pre-launch banner — revert the `.prelaunch-banner` | |
| 235 | block in `src/views/layout.tsx` that was added in commit | |
| 236 | `4a52a98`. | |
| 237 | 2. Commit: `feat(launch): remove pre-launch banner`. | |
| 238 | 3. Push — the container redeploys automatically. | |
| 239 | ||
| 240 | --- | |
| 241 | ||
| 242 | ## Known limitations at launch | |
| 243 | ||
| 244 | - **No legal pages** — see `docs/legal-audit.md`; needs an owner | |
| 245 | decision on ToS / Privacy before broad public signups. | |
| 246 | - **No billing** — free forever, or bolt on Stripe later. | |
| 247 | - **18 remaining `tsc` errors in locked files** — they don't block | |
| 248 | runtime; clean-up tracked separately. | |
| 249 | ||
| 250 | --- | |
| 251 | ||
| 252 | ## Troubleshooting | |
| 253 | ||
| 254 | | Symptom | Likely cause | Fix | | |
| 255 | |---|---|---| | |
| 256 | | `git clone` reports "empty repo" | The repo has no commits. | Push at least one commit first — an empty bare repo has no refs to advertise. | | |
| 257 | | Smart HTTP returns `404` on `info/refs` | `GIT_REPOS_PATH` is wrong or the volume isn't mounted with write access. | Check the volume mount in `fly.toml` / Railway; confirm the container user can read the bare repo dir. | | |
| 258 | | WebAuthn / passkey registration fails | `WEBAUTHN_RP_ID` doesn't match the domain, or includes a scheme/port. | Must be the bare host (`gluecron.com`); ensure `WEBAUTHN_ORIGIN` matches what the browser sees, including `https://`. | | |
| 259 | | GateTest callbacks rejected with `401` | `GATETEST_CALLBACK_SECRET` mismatch between Gluecron and GateTest. | Re-generate the secret and set the same value on both services. | | |
| 260 | | Crontech deploys fail with `401` | `GLUECRON_WEBHOOK_SECRET` is empty or mismatched. | Set to the same value on both services; the config default is empty, which Crontech rejects. | | |
| 261 | | Outbound emails don't arrive | `EMAIL_PROVIDER` defaults to `log`. | Set `EMAIL_PROVIDER=resend` and configure `RESEND_API_KEY` + `EMAIL_FROM`. | | |
| 262 | ||
| 263 | --- | |
| 264 | ||
| b105d39 | 265 | *Last reviewed: 2026-04-16.* |