Skip to content

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 production

Production setup ​

  • Profile: the dev, deploy and destroy scripts in packages/infra use the Alchemy profile shoot-grow. In GitHub Actions there is no profile; .github/workflows/deploy.yml authenticates with the CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID secrets and deploys the production stage on every push to master.
  • Domain: with ROOT_DOMAIN set (a GitHub variable in CI), the web app is served at app.<root>, the API at api.<root> and the docs at docs.<root>. Set CORS_ORIGIN to https://app.<root>.
  • Files: with R2_ENABLED=true the files bucket 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 ​

ResourceDefined in alchemy.run.ts
D1 database database with migrations from packages/db/src/migrationsdb
R2 bucket filesfiles
Queues jobs and jobs-dlq, plus the jobs-consumer bindingjobs, 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 ​

  1. Before first production deploy: confirm bun run db:check, bun run check-types, bun run test pass.
  2. Deploy. Migrations apply as part of the D1 resource; already-applied migrations are skipped.
  3. Set CORS_ORIGIN to the exact deployed web origin and deploy the server again (first deploy only).
  4. Set OWNER_PASSWORD (at least 12 characters) before the first deploy: the server creates the owner account from it on its first request. If it is missing or too short, the server logs [auth] seat bootstrap failed and 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.

  1. Build with bun run --cwd apps/clipper package. It writes the executables and dist/releases.json (sizes and SHA-256).
  2. Upload each file to its key. The repo has no upload command for releases; this step is manual.
  3. Set clipper.latestVersion and clipper.minVersion in 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.

NameRequiredPurpose
CORS_ORIGINyesComma-separated exact web origins, e.g. https://app.example.com
BETTER_AUTH_SECRETyesSession signing secret. Rotating it signs everyone out
BETTER_AUTH_URLyesPublic URL of the server
OWNER_PASSWORDyesBootstrap owner password. Rotate after first login
CLOUDFLARE_EMAIL_API_TOKENemailAPI token allowed to send email. Without it, production email stays queued
CLOUDFLARE_ACCOUNT_IDemailYour Cloudflare account id
EMAIL_FROMemailVerified sender, e.g. Shoot&Grow <hello@mail.example.com>
research variablesoptionalSee packages/infra/alchemy.run.ts
Clipper transcription and scoringoptionalOPENAI_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 ​

  1. In the Cloudflare dashboard open Email Service and onboard shootandgrow.com for sending. Add the DNS records it shows (SPF, DKIM) and wait until the domain is active.
  2. Create an API token with permission to send email for the account and store it as CLOUDFLARE_EMAIL_API_TOKEN. Set CLOUDFLARE_ACCOUNT_ID to your account id.
  3. EMAIL_FROM defaults to Shoot&Grow <hello@shootandgrow.com>. Set it only to use another address on the onboarded domain; other domains are rejected.
  4. Redeploy the server. GET /health should 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 ​

Endpoint200 means503 means
GET /healthstatus is ok (degraded if email is not configured or has failed rows)database unreachable
GET /readythe database answersdatabase unreachable
GET /OKnot 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 ​

  1. Write the migration in packages/db/src/migrations and run bun run db:check.
  2. Deploy the stage. D1 applies only unapplied migrations.
  3. Check /ready and the affected screens.

Never edit or delete a migration that has been applied to production.

Rollback ​

  1. 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).
  2. If a bad migration ran, forward-fix with a new migration. Restore from a D1 point-in-time restore only when data is damaged.
  3. 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.

Internal documentation. Not for clients.