Appearance
Deployment
Everything deploys with Alchemy from packages/infra.
bash
cd packages/infra && bunx alchemy profile edit # once
bun run deploy # personal dev_<user> stage
cd packages/infra && bunx alchemy deploy --stage productionProduction setup
- Profile: the
dev,deployanddestroyscripts inpackages/infrause the Alchemy profileshoot-grow. In GitHub Actions there is no profile;.github/workflows/deploy.ymlauthenticates with theCLOUDFLARE_API_TOKENandCLOUDFLARE_ACCOUNT_IDsecrets and deploys theproductionstage on every push tomaster. - Domain: with
ROOT_DOMAINset (a GitHub variable in CI), the web app is served atapp.<root>, the API atapi.<root>and the docs atdocs.<root>. SetCORS_ORIGINtohttps://app.<root>. - Files: with
R2_ENABLED=truethefilesbucket is created and used. Without it the server keeps files in D1 (packages/api/src/d1-storage.ts), which suits small files only; move to R2 before storing footage. R2 must be enabled on the Cloudflare account first.
What a stage contains
| Resource | Defined in alchemy.run.ts |
|---|---|
D1 database database with migrations from packages/db/src/migrations | db |
R2 bucket files | files |
Queues jobs and jobs-dlq, plus the jobs-consumer binding | jobs, jobsDeadLetter |
Worker server with bindings DB, FILES, JOBS, AI, CLOUDFLARE_EMAIL_API_TOKEN, CLOUDFLARE_ACCOUNT_ID, EMAIL_FROM, crons * * * * * (email) and */15 * * * * (sweeps) | server |
Web site (apps/web, Vite) | in the stack |
The R2 bucket needs a CORS rule for the web origin before browser uploads work, and presigning needs R2 S3 credentials as secrets. Both arrive with milestone 7.
Order of operations
- Before first production deploy: confirm
bun run db:check,bun run check-types,bun run testpass. - Deploy. Migrations apply as part of the D1 resource; already-applied migrations are skipped.
- Set
CORS_ORIGINto the exact deployed web origin and deploy the server again (first deploy only). - Set
OWNER_PASSWORD(at least 12 characters) before the first deploy: the server creates theowneraccount from it on its first request. If it is missing or too short, the server logs[auth] seat bootstrap failedand no owner exists. There is no other way to create an owner. To change the owner's password, change the secret and deploy.
Rolling forward, not back
Migrations are append-only, so a bad release is fixed by deploying a new release with a corrective migration. Make schema changes backward compatible with the previous build for one release (add columns as nullable or with defaults; stop reading a column one release before dropping it), because the old Worker may still serve requests while a new migration applies.
The docs site
docs is a static site in the Alchemy stack (Cloudflare.Website.StaticSite in packages/infra/alchemy.run.ts): it runs bun run build in apps/docs and serves .vitepress/dist as static assets. Its URL is passed to the web build as VITE_DOCS_URL, so planned screens link to it with no manual step. Locally the docs run on port 3010 (bun run dev in apps/docs).
Publishing the Clipper app
The Clipper desktop app is downloaded from this server, not from a store. Each platform's build is one file in the FILES bucket at clipper/releases/<platform>/clipper (clipper.exe on Windows). Platforms are linux, windows, macos-arm64 and macos-x64. GET /clipper/v1/download/<platform> serves the file.
- Build with
bun run --cwd apps/clipper package. It writes the executables anddist/releases.json(sizes and SHA-256). - Upload each file to its key. The repo has no upload command for releases; this step is manual.
- Set
clipper.latestVersionandclipper.minVersionin Settings so the app can ask users to update.
Only the Linux build has been run. The Windows and macOS builds are cross-compiled and untested (Clipper app).
Server configuration
Set these as Alchemy secrets or plain bindings for the stage (packages/infra/alchemy.run.ts). The server logs the names of missing required settings at startup, never values.
| Name | Required | Purpose |
|---|---|---|
CORS_ORIGIN | yes | Comma-separated exact web origins, e.g. https://app.example.com |
BETTER_AUTH_SECRET | yes | Session signing secret. Rotating it signs everyone out |
BETTER_AUTH_URL | yes | Public URL of the server |
OWNER_PASSWORD | yes | Bootstrap owner password. Rotate after first login |
CLOUDFLARE_EMAIL_API_TOKEN | API token allowed to send email. Without it, production email stays queued | |
CLOUDFLARE_ACCOUNT_ID | Your Cloudflare account id | |
EMAIL_FROM | Verified sender, e.g. Shoot&Grow <hello@mail.example.com> | |
| research variables | optional | See packages/infra/alchemy.run.ts |
| Clipper transcription and scoring | optional | OPENAI_API_KEY for transcription through an OpenAI-compatible endpoint; without it the AI binding is used. Scoring uses the research LLM (RESEARCH_LLM, ANTHROPIC_API_KEY). Without a transcription backend the Clipper runs offline only. |
Payments use Stripe Checkout. Set STRIPE_SECRET_KEY to a restricted key with write access to Checkout Sessions only, and STRIPE_WEBHOOK_SECRET to the signing secret of a webhook endpoint at https://<api>/webhooks/stripe that listens for checkout.session.completed and checkout.session.async_payment_succeeded. Both are optional: without them the app runs and payment links are simply not created.
Cloudflare Email setup
- In the Cloudflare dashboard open Email Service and onboard
shootandgrow.comfor sending. Add the DNS records it shows (SPF, DKIM) and wait until the domain is active. - Create an API token with permission to send email for the account and store it as
CLOUDFLARE_EMAIL_API_TOKEN. SetCLOUDFLARE_ACCOUNT_IDto your account id. EMAIL_FROMdefaults toShoot&Grow <hello@shootandgrow.com>. Set it only to use another address on the onboarded domain; other domains are rejected.- Redeploy the server.
GET /healthshould then report"email": { "configured": true }. While the account is on a plan that sends only to verified destination addresses, other recipients are refused: upgrade before launch.
Emails are written to an outbox table first and flushed by a cron every minute. Each email is sent at most once (the outbox id is the provider idempotency key). Transient provider errors retry with backoff and fail after five attempts; failed rows show in /health.
Health checks and smoke test
| Endpoint | 200 means | 503 means |
|---|---|---|
GET /health | status is ok (degraded if email is not configured or has failed rows) | database unreachable |
GET /ready | the database answers | database unreachable |
GET / | OK | not applicable |
After each deploy run bun run ops:smoke https://<server origin>. It checks /health, /ready, the security headers, and that unknown public links return 404. Then open the web app, sign in as owner, and check the dashboard. Failures exit non-zero, so the smoke test can gate a deploy.
Database backup and restore
D1 keeps point-in-time restore for the database, so restore is the first option. For a portable copy, run D1_DATABASE=<database-name> bun run ops:backup, which writes a dated SQL file under backups/. Copy it off the machine the same day. Restore steps and the monthly drill are in scripts/ops/restore-d1.md.
Logs: Workers Logs is enabled on the server Worker (observability in packages/infra/alchemy.run.ts). Each request writes one JSON line with event: "request", requestId, role, route, status, ms, and slow; errors write event: "error" with the same request id. Day-to-day use is in operations.md.
Migration procedure
- Write the migration in
packages/db/src/migrationsand runbun run db:check. - Deploy the stage. D1 applies only unapplied migrations.
- Check
/readyand the affected screens.
Never edit or delete a migration that has been applied to production.
Rollback
- Redeploy the previous Worker build from the last good commit. Schema changes stay in place because they are backward compatible for one release (see above).
- If a bad migration ran, forward-fix with a new migration. Restore from a D1 point-in-time restore only when data is damaged.
- Pending email rows are kept, not lost. They send after the rollback once the email token is set.
Rotating OWNER_PASSWORD and BETTER_AUTH_SECRET
OWNER_PASSWORD: change the secret, deploy, sign in, then change the owner password in the app. Do not reuse the bootstrap value.BETTER_AUTH_SECRET: change the secret and deploy. All sessions end and users sign in again. Plan it for a quiet time.