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.

DEPLOYMENT_RUNBOOK.mdBlame265 lines · 2 contributors

Normal view Raw

7703650Claude	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:
	41	`postgresql://user:pass@ep-xxx.eu-west-2.aws.neon.tech/neondb?sslmode=require`
	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 \
b105d39Dictation App	63	DATABASE_URL="<DATABASE_URL_FROM_NEON>" \
7703650Claude	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	\|---\|---\|---\|---\|
b105d39Dictation App	106	\| `DATABASE_URL` \| Yes \| `<DATABASE_URL_FROM_NEON>` \| Neon pooled connection string. \|
7703650Claude	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	\|---\|---\|---\|---\|
	124	\| `GATETEST_URL` \| Yes (for integration) \| `https://gatetest.io/api/scan/run` \| Default `https://gatetest.ai/api/scan/run` — override to production host. \|
	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
b105d39Dictation App	265	Last reviewed: 2026-04-16.