Skip to content

Open source alternative to Semrush and Ahrefs

Deploy production from a manual GitHub workflow with GitHub-held secrets (#652)

Ben Senescucb82159dfa5b
diff --git a/.github/workflows/deploy-production.yml b/.github/workflows/deploy-production.yml
new file mode 100644
index 00000000..1a10c6fe
--- /dev/null
+++ b/.github/workflows/deploy-production.yml
@@ -0,0 +1,145 @@
+name: Deploy production
+
+# Maintainer setup and the optional team CLI alias:
+# docs/maintainers/production-deployment.md
+on:
+ workflow_dispatch:
+
+permissions:
+ contents: read
+
+# Never cancel a deployment while migrations or resource updates are running.
+concurrency:
+ group: deploy-hosted-prod
+ cancel-in-progress: false
+
+jobs:
+ deploy:
+ # The public mirror must not deploy production. Only dispatches on main
+ # may use the production environment's credentials.
+ if: github.repository == 'bensenescu/open-seo' && github.ref == 'refs/heads/main'
+ runs-on: ubuntu-latest
+ timeout-minutes: 30
+ environment:
+ name: production
+ url: https://app.openseo.so
+ env:
+ # Shared by Vite's client build and Alchemy's runtime configuration.
+ AUTH_MODE: hosted
+ DATABASE_PROVIDER: postgres
+ BETTER_AUTH_URL: https://app.openseo.so
+ BYPASS_EMAIL_VERIFICATION: "false"
+ CLOUDFLARE_ACCOUNT_ID: ${{ vars.CLOUDFLARE_ACCOUNT_ID }}
+ HYPERDRIVE_ID: ${{ vars.HYPERDRIVE_ID }}
+ GOOGLE_CLIENT_ID: ${{ vars.GOOGLE_CLIENT_ID }}
+ TURNSTILE_SITE_KEY: ${{ vars.TURNSTILE_SITE_KEY }}
+ LOOPS_TRANSACTIONAL_VERIFY_EMAIL_ID: ${{ vars.LOOPS_TRANSACTIONAL_VERIFY_EMAIL_ID }}
+ LOOPS_TRANSACTIONAL_RESET_PASSWORD_ID: ${{ vars.LOOPS_TRANSACTIONAL_RESET_PASSWORD_ID }}
+ LOOPS_TRANSACTIONAL_INVITATION_ID: ${{ vars.LOOPS_TRANSACTIONAL_INVITATION_ID }}
+ LOOPS_PRODUCT_UPDATES_LIST_ID: ${{ vars.LOOPS_PRODUCT_UPDATES_LIST_ID }}
+ META_PIXEL_ID: ${{ vars.META_PIXEL_ID }}
+ POSTHOG_PUBLIC_KEY: ${{ vars.POSTHOG_PUBLIC_KEY }}
+ POSTHOG_HOST: ${{ vars.POSTHOG_HOST }}
+ OPENROUTER_MODEL: ${{ vars.OPENROUTER_MODEL }}
+ OPENSEO_TELEMETRY_DISABLED: ${{ vars.OPENSEO_TELEMETRY_DISABLED }}
+
+ steps:
+ - name: Checkout dispatched commit
+ uses: actions/checkout@v4
+ with:
+ ref: ${{ github.sha }}
+ persist-credentials: false
+
+ - name: Validate production configuration
+ shell: bash
+ env:
+ CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+ POSTGRES_DATABASE_URL: ${{ secrets.POSTGRES_DATABASE_URL }}
+ DATAFORSEO_API_KEY: ${{ secrets.DATAFORSEO_API_KEY }}
+ BETTER_AUTH_SECRET: ${{ secrets.BETTER_AUTH_SECRET }}
+ CRAWLER_ACCESS_SECRET: ${{ secrets.CRAWLER_ACCESS_SECRET }}
+ GOOGLE_CLIENT_SECRET: ${{ secrets.GOOGLE_CLIENT_SECRET }}
+ TURNSTILE_SECRET_KEY: ${{ secrets.TURNSTILE_SECRET_KEY }}
+ LOOPS_API_KEY: ${{ secrets.LOOPS_API_KEY }}
+ AUTUMN_SECRET_KEY: ${{ secrets.AUTUMN_SECRET_KEY }}
+ AUTUMN_WEBHOOK_SECRET: ${{ secrets.AUTUMN_WEBHOOK_SECRET }}
+ CONTEXT_API_KEY: ${{ secrets.CONTEXT_API_KEY }}
+ OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
+ DUB_API_KEY: ${{ secrets.DUB_API_KEY }}
+ META_CONVERSIONS_API_TOKEN: ${{ secrets.META_CONVERSIONS_API_TOKEN }}
+ GDPR_ERASURE_SECRET: ${{ secrets.GDPR_ERASURE_SECRET }}
+ run: |
+ # Alchemy replaces the worker's complete var/secret set on every
+ # deploy, and most values are optional-with-empty-default in the
+ # stack. A missing one would deploy cleanly and silently disable
+ # that integration, so require everything production depends on.
+ required=(CLOUDFLARE_API_TOKEN POSTGRES_DATABASE_URL
+ CLOUDFLARE_ACCOUNT_ID HYPERDRIVE_ID
+ DATAFORSEO_API_KEY BETTER_AUTH_SECRET CRAWLER_ACCESS_SECRET
+ GOOGLE_CLIENT_ID GOOGLE_CLIENT_SECRET
+ TURNSTILE_SITE_KEY TURNSTILE_SECRET_KEY
+ LOOPS_API_KEY LOOPS_TRANSACTIONAL_VERIFY_EMAIL_ID
+ LOOPS_TRANSACTIONAL_RESET_PASSWORD_ID
+ LOOPS_TRANSACTIONAL_INVITATION_ID
+ AUTUMN_SECRET_KEY AUTUMN_WEBHOOK_SECRET)
+ optional=(CONTEXT_API_KEY OPENROUTER_API_KEY DUB_API_KEY
+ META_CONVERSIONS_API_TOKEN GDPR_ERASURE_SECRET
+ LOOPS_PRODUCT_UPDATES_LIST_ID META_PIXEL_ID
+ POSTHOG_PUBLIC_KEY POSTHOG_HOST OPENROUTER_MODEL
+ OPENSEO_TELEMETRY_DISABLED)
+ failed=0
+ for name in "${required[@]}"; do
+ if [[ -z "${!name}" ]]; then
+ echo "::error::Missing production secret or variable: $name"
+ failed=1
+ fi
+ done
+ # Values pasted into GitHub's settings UI can keep a trailing line
+ # break, which would change signing keys and break API auth.
+ for name in "${required[@]}" "${optional[@]}"; do
+ if [[ "${!name}" =~ [[:space:]] ]]; then
+ echo "::error::$name contains whitespace or a line break; re-enter it"
+ failed=1
+ fi
+ done
+ exit "$failed"
+
+ - name: Setup pnpm
+ uses: pnpm/action-setup@v4
+
+ - name: Setup Node.js
+ uses: actions/setup-node@v4
+ with:
+ node-version: 22
+ cache: pnpm
+
+ - name: Install dependencies
+ run: pnpm install --frozen-lockfile
+
+ - name: Build
+ run: pnpm build
+
+ - name: Migrate production Postgres
+ run: pnpm db:migrate:pg
+ env:
+ POSTGRES_DATABASE_URL: ${{ secrets.POSTGRES_DATABASE_URL }}
+
+ - name: Deploy production Workers
+ # Alchemy reads secrets from the process environment (no --env-file).
+ # They are scoped to this step only.
+ run: pnpm alchemy deploy deploy/alchemy/alchemy.run.ts --stage hosted-prod --adopt --yes
+ env:
+ CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+ DATAFORSEO_API_KEY: ${{ secrets.DATAFORSEO_API_KEY }}
+ BETTER_AUTH_SECRET: ${{ secrets.BETTER_AUTH_SECRET }}
+ CRAWLER_ACCESS_SECRET: ${{ secrets.CRAWLER_ACCESS_SECRET }}
+ GOOGLE_CLIENT_SECRET: ${{ secrets.GOOGLE_CLIENT_SECRET }}
+ TURNSTILE_SECRET_KEY: ${{ secrets.TURNSTILE_SECRET_KEY }}
+ LOOPS_API_KEY: ${{ secrets.LOOPS_API_KEY }}
+ AUTUMN_SECRET_KEY: ${{ secrets.AUTUMN_SECRET_KEY }}
+ AUTUMN_WEBHOOK_SECRET: ${{ secrets.AUTUMN_WEBHOOK_SECRET }}
+ CONTEXT_API_KEY: ${{ secrets.CONTEXT_API_KEY }}
+ OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
+ DUB_API_KEY: ${{ secrets.DUB_API_KEY }}
+ META_CONVERSIONS_API_TOKEN: ${{ secrets.META_CONVERSIONS_API_TOKEN }}
+ GDPR_ERASURE_SECRET: ${{ secrets.GDPR_ERASURE_SECRET }}
diff --git a/.gitignore b/.gitignore
index afc6595a..53cf3c6f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -17,7 +17,6 @@ dist-sourcemaps/
.env.*
!.env.example
!.env.preview.example
-!.env.production.example
!.env.selfhost.example
.vercel
.output
diff --git a/deploy/.env.production.example b/deploy/.env.production.example
deleted file mode 100644
index 12562dfe..00000000
--- a/deploy/.env.production.example
+++ /dev/null
@@ -1,59 +0,0 @@
-# Alchemy PROD deploy (stage "prod") — adoption semantics and the
-# first-cutover checklist are in docs/maintainers/preview-deployments.md.
-# Cloudflare credentials come from `pnpm alchemy login`, not this file.
-#
-# cp deploy/.env.production.example .env.production
-# pnpm deploy:postgres
-
-AUTH_MODE=hosted
-BETTER_AUTH_URL=https://app.openseo.so
-# BETTER_AUTH_SECRET=
-# Encrypts saved Shopify crawler signatures; 32+ characters, distinct from
-# BETTER_AUTH_SECRET.
-# CRAWLER_ACCESS_SECRET=
-# DATAFORSEO_API_KEY=
-
-# Postgres through the existing Hyperdrive config. Cloudflare never returns
-# origin credentials, so alchemy needs them here (PlanetScale connection
-# settings).
-DATABASE_PROVIDER=postgres
-# HYPERDRIVE_ORIGIN_HOST=us-east-3.pg.psdb.cloud
-# HYPERDRIVE_ORIGIN_PORT=5432
-# HYPERDRIVE_ORIGIN_DATABASE=postgres
-# HYPERDRIVE_ORIGIN_USER=
-# HYPERDRIVE_ORIGIN_PASSWORD=
-
-# Hosted auth.
-# GOOGLE_CLIENT_ID=
-# GOOGLE_CLIENT_SECRET=
-# LOOPS_API_KEY=
-# LOOPS_TRANSACTIONAL_VERIFY_EMAIL_ID=
-# LOOPS_TRANSACTIONAL_RESET_PASSWORD_ID=
-# LOOPS_TRANSACTIONAL_INVITATION_ID=
-# LOOPS_PRODUCT_UPDATES_LIST_ID=
-# TURNSTILE_SECRET_KEY=
-# TURNSTILE_SITE_KEY=
-
-# Billing, analytics, agents.
-# AUTUMN_SECRET_KEY=
-# AUTUMN_WEBHOOK_SECRET=
-# Dub referral conversion tracking (leads + sales). Also requires, in the Dub
-# dashboard: openseo.so allowlisted under workspace Tracking settings, partner
-# link destinations kept on openseo.so, and the native Stripe integration
-# disconnected (sales are reported by the app; both would double count).
-# DUB_API_KEY=
-# Meta ad signup attribution (Conversions API). The same pixel id must be set
-# on the marketing site worker, which loads the pixel where the visitor's
-# advertising choice allows it.
-# META_PIXEL_ID=
-# META_CONVERSIONS_API_TOKEN=
-# Long random secret shared only with scripts/erase-user-data.ts.
-# GDPR_ERASURE_SECRET=
-# POSTHOG_PUBLIC_KEY=
-# POSTHOG_HOST=
-# OPENROUTER_API_KEY=
-# OPENROUTER_MODEL=
-
-# Optional: Context.dev key for the site audit "Render JavaScript" option.
-# Cloudflare Browser Run renders first; Context renders the pages it cannot.
-# CONTEXT_API_KEY=
diff --git a/deploy/alchemy/alchemy.run.ts b/deploy/alchemy/alchemy.run.ts
index 400b7aca..c8eaa028 100644
--- a/deploy/alchemy/alchemy.run.ts
+++ b/deploy/alchemy/alchemy.run.ts
@@ -29,8 +29,9 @@ import {
// deploy via `pnpm deploy:preview --stage <name>`; self-hosters via
// `pnpm deploy:selfhost` (stage "selfhost", no flag to pass).
// - Stage "hosted-prod": names the EXISTING openseo.so production resources
-// so `--adopt` imports them. Deploy via `pnpm deploy:postgres` (--adopt and
-// the stage baked in).
+// so `--adopt` imports them. Deployed only by the manual GitHub workflow
+// (.github/workflows/deploy-production.yml), which supplies secrets from
+// the GitHub `production` environment.
//
// Local dev and Docker self-host do NOT use this stack (wrangler.jsonc +
// @cloudflare/vite-plugin). This stack deploys the PREBUILT `vite build`
@@ -77,7 +78,6 @@ const PROD_NAMES = {
r2: "open-seo",
kv: "every-super-seo",
oauthKv: "OAUTH_KV",
- hyperdrive: "openseo",
} as const;
const makeResources = (stage: string) => {
@@ -121,36 +121,15 @@ const makeResources = (stage: string) => {
};
};
-/**
- * Prod-only: the existing Hyperdrive config pooling connections to the
- * production Postgres. Origin credentials come from the env file — Cloudflare
- * never returns them, so alchemy must know them to manage the config.
- */
-const makeHyperdrive = () =>
- Cloudflare.Hyperdrive.Connection("HYPERDRIVE", {
- name: PROD_NAMES.hyperdrive,
- origin: Config.all([
- Config.string("HYPERDRIVE_ORIGIN_HOST"),
- Config.string("HYPERDRIVE_ORIGIN_PORT").pipe(Config.withDefault("5432")),
- Config.string("HYPERDRIVE_ORIGIN_DATABASE"),
- Config.string("HYPERDRIVE_ORIGIN_USER"),
- Config.redacted("HYPERDRIVE_ORIGIN_PASSWORD"),
- ]).pipe(
- Config.map(([host, port, database, user, password]) => ({
- scheme: "postgres" as const,
- host,
- port: Number(port),
- database,
- user,
- password,
- })),
- ),
- // Prod runs with Hyperdrive caching OFF (no write invalidation for a SaaS
- // with per-user reads-after-writes).
- caching: { disabled: true },
- // Raise Postgres max_connections to 100 before deploying this pool limit.
- originConnectionLimit: 30,
- }).pipe(Alchemy.RemovalPolicy.retain());
+// Prod-only: the existing Hyperdrive config bound by ID. A managed
+// Hyperdrive.Connection would need the origin password on every deploy, so
+// the config (caching OFF, origin connection limit 30) is managed in the
+// Cloudflare dashboard instead.
+const hyperdriveBinding = (hyperdriveId: string) => ({
+ bindings: [
+ { type: "hyperdrive" as const, name: "HYPERDRIVE", id: hyperdriveId },
+ ],
+});
const optionalVar = (name: string) =>
Config.string(name).pipe(
@@ -261,10 +240,10 @@ const resolveSelfHostAccess = (
return { teamDomain, policyAud };
});
-// Secrets/vars resolve from the env file passed to `alchemy deploy`
-// (`Config.redacted` → Cloudflare `secret_text`, `Config.string` → plaintext
-// var). NOTE: the alchemy CLI loads `--env-file` into the Config environment,
-// NOT into process.env — a process.env read here silently yields "".
+// Secrets/vars resolve from Config (`Config.redacted` → Cloudflare
+// `secret_text`, `Config.string` → plaintext var). Previews and self-host pass
+// an `--env-file`, which the alchemy CLI loads into Config, NOT process.env;
+// the production workflow exports them as job/step env instead.
const dataEnv = {
// AUTH_MODE, DATABASE_PROVIDER, BETTER_AUTH_URL, TEAM_DOMAIN, and
// POLICY_AUD are stage-dependent and set in the stack body below.
@@ -298,8 +277,9 @@ const dataEnv = {
POSTHOG_HOST: optionalVar("POSTHOG_HOST"),
TURNSTILE_SECRET_KEY: optionalSecret("TURNSTILE_SECRET_KEY"),
TURNSTILE_SITE_KEY: optionalVar("TURNSTILE_SITE_KEY"),
- // Alchemy reconciles worker vars on every deploy, so the telemetry opt-out
- // must live in the env file — a dashboard-set var would be wiped.
+ // Alchemy reconciles worker vars and secrets on every deploy, so every value
+ // must come from the env file / GitHub environment — a dashboard-set one
+ // would be wiped.
OPENSEO_TELEMETRY_DISABLED: optionalVar("OPENSEO_TELEMETRY_DISABLED"),
};
@@ -322,6 +302,14 @@ export default Alchemy.Stack(
Config.withDefault("cloudflare_access"),
);
const databaseProvider = yield* optionalVar("DATABASE_PROVIDER");
+ const hyperdriveId = prod ? yield* Config.string("HYPERDRIVE_ID") : "";
+ if (prod && (authMode !== "hosted" || databaseProvider !== "postgres")) {
+ return yield* Effect.die(
+ new Error(
+ "hosted-prod requires AUTH_MODE=hosted and DATABASE_PROVIDER=postgres.",
+ ),
+ );
+ }
const workersSubdomain = yield* readWorkersSubdomain({ required: false });
// Auth needs an absolute BETTER_AUTH_URL. Prod sets it explicitly;
@@ -333,16 +321,7 @@ export default Alchemy.Stack(
if (!authUrl) {
return yield* Effect.die(
new Error(
- "Set BETTER_AUTH_URL (https://app.openseo.so) in .env.production.",
- ),
- );
- }
- // Prod must say which database it runs on. A silently-defaulted "d1"
- // would deploy cleanly against the stale pre-Postgres data.
- if (databaseProvider !== "postgres" && databaseProvider !== "d1") {
- return yield* Effect.die(
- new Error(
- "Set DATABASE_PROVIDER explicitly in .env.production (prod runs postgres).",
+ "Set BETTER_AUTH_URL (https://app.openseo.so) in the production workflow.",
),
);
}
@@ -369,7 +348,6 @@ export default Alchemy.Stack(
// Created once and bound into BOTH workers — they share the same
// D1/KV/R2 (and prod Hyperdrive). OAUTH_KV stays app-worker-only.
const resources = makeResources(stage);
- const prodHyperdrive = prod ? makeHyperdrive() : undefined;
// Aux worker: the site-audit engine (src/audit-worker.ts) — the
// SiteAuditWorkflow orchestrator and the per-audit AuditScratchpad DO.
@@ -415,7 +393,6 @@ export default Alchemy.Stack(
POSTHOG_HOST: dataEnv.POSTHOG_HOST,
AUTH_MODE: authMode,
DATABASE_PROVIDER: databaseProvider || "d1",
- ...(prodHyperdrive ? { HYPERDRIVE: prodHyperdrive } : {}),
// This worker is the code home of the scratchpad DO and the
// site-audit workflow; the app worker binds to both cross-script.
AUDIT_SCRATCHPAD: Cloudflare.DurableObject("AUDIT_SCRATCHPAD", {
@@ -432,6 +409,10 @@ export default Alchemy.Stack(
},
}).pipe(Alchemy.RemovalPolicy.retain(prod));
+ if (prod) {
+ yield* auditWorker.bind("hyperdrive", hyperdriveBinding(hyperdriveId));
+ }
+
const app = yield* Cloudflare.Worker("open-seo", {
name: workerName(stage),
// Prod serves the real domains; the zone is inferred from the hostname.
@@ -485,9 +466,6 @@ export default Alchemy.Stack(
TEAM_DOMAIN: access.teamDomain,
POLICY_AUD: access.policyAud,
- // Prod-only: pooled Postgres via the existing Hyperdrive config.
- ...(prodHyperdrive ? { HYPERDRIVE: prodHyperdrive } : {}),
-
// Service binding to the audit worker's AuditEngine entrypoint
// (cancel + GDPR erasure of scratchpad state; env key = binding
// name).
@@ -545,6 +523,10 @@ export default Alchemy.Stack(
Alchemy.RemovalPolicy.retain(prod),
);
+ if (prod) {
+ yield* app.bind("hyperdrive", hyperdriveBinding(hyperdriveId));
+ }
+
return { url: app.url.as<string>() };
}),
);
diff --git a/docs/maintainers/preview-deployments.md b/docs/maintainers/preview-deployments.md
index ef0d15ef..f87eed2a 100644
--- a/docs/maintainers/preview-deployments.md
+++ b/docs/maintainers/preview-deployments.md
@@ -90,7 +90,7 @@ pnpm deploy:preview --stage manual-preview --yes
`.env.preview`; extra flags land on the deploy. CI runs this same command.
Two alchemy conventions to know: omitting `--stage` targets alchemy's default
per-user stage (`dev_$USER`), and stage `hosted-prod` with `.env.preview` fails
-in the stack (no `BETTER_AUTH_URL`) — use `pnpm deploy:postgres` for production.
+in the stack: production requires hosted auth, Postgres, and existing resource IDs.
Each preview starts with an empty database: open the URL, pass the Access
challenge, and you're in. Previews default to `AUTH_MODE=local_noauth`, so
@@ -145,55 +145,11 @@ pnpm destroy:preview --stage pub-<pr> --yes
## Production
-Production deploys through the same Alchemy stack, stage `hosted-prod`, which
-names the existing production resources so `--adopt` imports them instead of
-creating fresh ones. Its domains do not match the preview Access wildcard.
-(The stage is `hosted-prod`, not `prod`, so a self-hoster's stage name can
-never collide with the adoption path.)
-
-```sh
-pnpm deploy:postgres
-```
-
-The script runs the Postgres migrations (`db:migrate:pg`), builds, and then
-`alchemy deploy --env-file .env.production --stage hosted-prod --adopt` —
-`--adopt` and the stage are baked in so they cannot be forgotten, and alchemy
-shows the plan for approval before applying. It uses the same
-`pnpm alchemy login` credential as previews (make sure `query_cache:write`
-was enabled for Hyperdrive).
-
-### First-cutover checklist (one time)
-
-The first Alchemy prod deploy adopts live resources. Before running it:
-
-1. Append `--dry-run` to the alchemy command and read the plan — every prod
- resource (D1 `open-seo`, KV `every-super-seo`/`OAUTH_KV`, R2 `open-seo`,
- Hyperdrive `openseo`, Worker `open-seo`) should be adopted, none created.
-2. Diff `.env.production` against the live worker's secrets
- (`GET /accounts/:id/workers/scripts/open-seo/secrets`): alchemy's deploy
- replaces the COMPLETE binding set, so any live secret missing from the env
- file deploys as `""` — most vars are optional-with-empty-default, so the
- deploy succeeds while silently disabling that integration.
-3. Rehearse adoption on a scratch stage that mirrors prod's shape — deploy
- the scratch worker **with wrangler first** (including the `migrations`
- block) so it carries a wrangler-era migration tag and live DO namespaces
- like prod; a fresh alchemy stage skips the exact adoption path prod will
- take.
-4. Compare `SELECT name FROM d1_migrations` on the prod D1 against
- `ls drizzle/*.sql` — alchemy applies any missing D1 migrations on the
- first deploy (wrangler-compatible ledger, verified), and the dormant prod
- D1 hasn't been migrated since the Postgres cutover.
-5. Confirm the `HYPERDRIVE_ORIGIN_*` values in `.env.production` match the
- live Hyperdrive config — Cloudflare never returns origin credentials, so a
- mismatch would rewrite the origin.
-6. Note: prod already serves on `open-seo.<subdomain>.workers.dev` (alchemy
- keeps it enabled; the workers.dev toggle never appears in `--dry-run`).
- The prod resources (worker, D1, R2, KV, Hyperdrive) carry alchemy's
- `RemovalPolicy.retain`, stamped into state on the first prod deploy: a
- destroy of stage `hosted-prod` forgets state but leaves the live resources
- untouched. (Workflow registrations are the exception — they're created
- inside the worker provider and aren't individually retainable — but
- re-registering a workflow is a lossless upsert.)
+OpenSEO's hosted production deploys through the manually dispatched
+`Deploy production` GitHub workflow (Alchemy stage `hosted-prod`, secrets held
+in the GitHub `production` environment). See
+[production deployment](production-deployment.md). Local preview deployment commands do
+not deploy production.
## Self-hosting on Cloudflare
diff --git a/docs/maintainers/production-deployment.md b/docs/maintainers/production-deployment.md
new file mode 100644
index 00000000..ea11b324
--- /dev/null
+++ b/docs/maintainers/production-deployment.md
@@ -0,0 +1,115 @@
+# Production deployment
+
+The `Deploy production` GitHub workflow builds the dispatched `main` commit,
+runs Postgres migrations, then deploys Alchemy stage `hosted-prod`. It runs only
+when dispatched in `bensenescu/open-seo` on `main`; pushes and PRs never trigger
+it. Runs serialize, and a newer dispatch does not cancel a running migration.
+
+No production secret lives on a developer machine. Everything the deploy needs
+is in the GitHub `production` environment; Cloudflare credentials, the database
+URL, and the application secrets are exposed only to the steps that use them.
+
+## One-time setup
+
+Create a `production` environment in the repository settings and restrict its
+deployment branches to `main`. Then add the following.
+
+### Secrets
+
+| Secret | Purpose |
+| ---------------------------- | ------------------------------------------------------------------ |
+| `CLOUDFLARE_API_TOKEN` | Alchemy deployment and remote state authentication |
+| `POSTGRES_DATABASE_URL` | Drizzle migrations against the same database Hyperdrive fronts |
+| `DATAFORSEO_API_KEY` | base64 `login:password` (not the dashboard key) |
+| `BETTER_AUTH_SECRET` | Must be the existing value: it encrypts stored Google OAuth tokens |
+| `CRAWLER_ACCESS_SECRET` | Must be the existing value: it encrypts stored crawler signatures |
+| `GOOGLE_CLIENT_SECRET` | Hosted Google sign-in and Search Console / GA4 OAuth |
+| `TURNSTILE_SECRET_KEY` | Signup captcha verification |
+| `LOOPS_API_KEY` | Transactional email and contact sync |
+| `AUTUMN_SECRET_KEY` | Billing |
+| `AUTUMN_WEBHOOK_SECRET` | Billing webhook verification |
+| `OPENROUTER_API_KEY` | SAM chat agent (optional) |
+| `DUB_API_KEY` | Referral tracking (optional) |
+| `CONTEXT_API_KEY` | Site audit JavaScript rendering fallback (optional) |
+| `META_CONVERSIONS_API_TOKEN` | Meta ad signup attribution (optional) |
+| `GDPR_ERASURE_SECRET` | `scripts/erase-user-data.ts` endpoint (optional) |
+
+Copy the current production values from the live worker before the first run.
+Alchemy replaces the worker's complete var and secret set on every deploy, so a
+secret missing from GitHub deploys as empty and silently disables that
+integration. The workflow fails early if any required one is unset; the
+optional ones simply turn their feature off.
+
+The Cloudflare token needs the permissions the Alchemy stack already uses:
+Workers scripts, D1, KV, R2, Workflows, custom-domain management, Account
+Settings Read, and Secrets Store Read (Alchemy fetches its state-store token
+from the account Secrets Store each run, so no extra GitHub secret is needed).
+
+### Variables
+
+| Variable | Value |
+| --------------------------------------- | ---------------------------------------------- |
+| `CLOUDFLARE_ACCOUNT_ID` | Production account ID |
+| `HYPERDRIVE_ID` | Existing `openseo` Hyperdrive configuration ID |
+| `GOOGLE_CLIENT_ID` | Existing Google OAuth client ID |
+| `TURNSTILE_SITE_KEY` | Existing public Turnstile site key |
+| `LOOPS_TRANSACTIONAL_VERIFY_EMAIL_ID` | Verification template ID |
+| `LOOPS_TRANSACTIONAL_RESET_PASSWORD_ID` | Password-reset template ID |
+| `LOOPS_TRANSACTIONAL_INVITATION_ID` | Invitation template ID |
+| `LOOPS_PRODUCT_UPDATES_LIST_ID` | Product-updates mailing list ID; optional |
+| `META_PIXEL_ID` | Meta pixel ID for signup attribution; optional |
+| `POSTHOG_PUBLIC_KEY`, `POSTHOG_HOST` | Existing analytics configuration; optional |
+| `OPENROUTER_MODEL` | Optional model override |
+| `OPENSEO_TELEMETRY_DISABLED` | Optional telemetry setting |
+
+The workflow fixes `AUTH_MODE=hosted`, `DATABASE_PROVIDER=postgres`,
+`BETTER_AUTH_URL=https://app.openseo.so`, and email verification enabled.
+
+### Hyperdrive
+
+Keep the existing `openseo` Hyperdrive configuration and copy its ID into
+`HYPERDRIVE_ID`. Alchemy binds it to both Workers by ID rather than managing it,
+so origin credentials, caching (keep it disabled), and the origin connection
+limit (30) are changed in the Cloudflare dashboard, not in a deploy. The stack previously declared this
+config as a managed resource with `RemovalPolicy.retain`; the first deployment
+plan should show it being forgotten from state, not deleted.
+
+## Trigger a deploy
+
+Use Actions > Deploy production > Run workflow, or from any machine
+authenticated to GitHub:
+
+```sh
+pnpm deploy:prod
+```
+
+The command queues the workflow and returns; follow the run in GitHub Actions.
+It deploys the remote `main` commit, not uncommitted local changes. If migrations
+succeed but the deploy fails, the schema changes remain, so keep migrations
+compatible with the currently deployed app.
+
+To rotate an application secret, update it in the GitHub environment and run the
+workflow again. Rotating `BETTER_AUTH_SECRET` still needs a separate
+data-encryption migration plan, as does `CRAWLER_ACCESS_SECRET`.
+
+## If a deploy breaks production
+
+Pick the fastest option that fits. Migrations are never rolled back; keep them
+backward compatible so any of these is safe.
+
+1. **Bad code, config unchanged.** Cloudflare dashboard > Workers > `open-seo`
+ > Deployments > roll back to the previous version. Same for `open-seo-audit`
+ > if it changed. Takes seconds. Alchemy state does not know about the
+ > rollback, so the next workflow run redeploys whatever `main` is at.
+2. **Bad commit.** `git revert` it on `main`, merge, then dispatch the workflow
+ again. The workflow only deploys `main`, so this is the normal way to ship
+ an older state.
+3. **Workflow itself is broken.** Deploy from a machine that still has a
+ `.env.production` (add `HYPERDRIVE_ID`; the `HYPERDRIVE_ORIGIN_*` lines are
+ no longer read):
+
+ ```sh
+ pnpm build && pnpm alchemy deploy deploy/alchemy/alchemy.run.ts --env-file .env.production --stage hosted-prod --adopt
+ ```
+
+ The stack is identical, so this and the workflow can be used interchangeably.
diff --git a/docs/maintainers/runbooks/d1-to-postgres-detailed.md b/docs/maintainers/runbooks/d1-to-postgres-detailed.md
index 33d598c9..16f4e915 100644
--- a/docs/maintainers/runbooks/d1-to-postgres-detailed.md
+++ b/docs/maintainers/runbooks/d1-to-postgres-detailed.md
@@ -9,10 +9,10 @@ copies the data into a freshly-migrated Postgres database using
`scripts/migrate-d1-to-postgres.ts`. For the condensed happy path see
[d1-to-postgres-simple.md](./d1-to-postgres-simple.md).
-> **Scope:** this runbook is for the OpenSEO production deployment —
-> `pnpm deploy:postgres` is hardwired to alchemy stage `hosted-prod`, its domains, and
-> `.env.production`. The alchemy self-host path (non-`prod` stages) has no
-> Hyperdrive wiring, so Postgres is not currently available to self-hosters.
+> **Scope:** this is the historical production data-copy procedure. Routine
+> schema migrations and deployments now run through the manual GitHub workflow;
+> see [production deployment](../production-deployment.md).
+> Self-hosted Alchemy stages do not provision Hyperdrive.
The script reads **each table directly from D1 over the Cloudflare REST API** and
writes to Postgres — there is no SQL dump to download or reimport. (An earlier
@@ -20,8 +20,7 @@ dump-based approach was dropped after a `wrangler d1 export` download silently
truncated yet reported success; reading tables over the API avoids that whole
class of failure and reads live, complete data.)
-D1 is left untouched throughout, so **rollback is just flipping the provider flag
-back to `d1`** until you've confirmed the Postgres cutover is healthy.
+D1 is left untouched throughout, so a rollback requires changing the deployment configuration back to D1 until you've confirmed the Postgres cutover is healthy.
> **Schema drift:** the script was authored 2026-06-29 and reflects the schema as
> of that date (it enumerates every table via Drizzle). If the schema changed
@@ -92,7 +91,7 @@ after cutover would collide with migrated rows.
Hyperdrive) and deploy:
```sh
- pnpm deploy:postgres
+ pnpm deploy:prod
```
4. **Verify.** Smoke-test the live app — load a project, save a keyword, check
diff --git a/docs/maintainers/runbooks/d1-to-postgres-simple.md b/docs/maintainers/runbooks/d1-to-postgres-simple.md
index cfb8e1c0..acc98833 100644
--- a/docs/maintainers/runbooks/d1-to-postgres-simple.md
+++ b/docs/maintainers/runbooks/d1-to-postgres-simple.md
@@ -7,14 +7,14 @@ detail — what the script converts, the low-downtime delta sync, cutover and
rollback — see
[d1-to-postgres-detailed.md](./d1-to-postgres-detailed.md).
-> **Scope:** this runbook is for the OpenSEO production deployment —
-> `pnpm deploy:postgres` is hardwired to alchemy stage `hosted-prod`, its domains, and
-> `.env.production`. The alchemy self-host path (non-`prod` stages) has no
-> Hyperdrive wiring, so Postgres is not currently available to self-hosters.
+> **Scope:** this is the historical production data-copy procedure. Routine
+> schema migrations and deployments now run through the manual GitHub workflow;
+> see [production deployment](../production-deployment.md).
+> Self-hosted Alchemy stages do not provision Hyperdrive.
> Switching `DATABASE_PROVIDER` to `postgres` changes where the app reads and
> writes — it does **not** move existing data. This copies the data. D1 is never
-> written to, so rollback is just flipping the provider back to `d1`.
+> written to, so a database rollback requires a separate deployment configuration change.
## 1. Credentials → `.env.local`
@@ -72,7 +72,7 @@ binding — the app only connects to Postgres through Hyperdrive) and deploy, th
smoke-test (load a project, save a keyword, check billing):
```sh
-pnpm deploy:postgres
+pnpm deploy:prod
```
> **Optional — freeze writes** for a perfectly consistent snapshot: pause the
diff --git a/docs/maintainers/runbooks/gdpr-erasure.md b/docs/maintainers/runbooks/gdpr-erasure.md
index e94a2cc4..3e652d0f 100644
--- a/docs/maintainers/runbooks/gdpr-erasure.md
+++ b/docs/maintainers/runbooks/gdpr-erasure.md
@@ -16,8 +16,9 @@ and in the operator environment as `GDPR_ERASURE_SECRET`. The secret enables a
single HMAC-authenticated endpoint at `/api/internal/gdpr-erasure/storage`; the
endpoint returns 404 when the secret is unset.
-Add `GDPR_ERASURE_SECRET` to `.env.production`, then deploy the Worker before
-using the command. Keep the secret out of shell history and logs.
+Add `GDPR_ERASURE_SECRET` to the GitHub `production` environment secrets, then
+deploy through the manual production workflow before using the command. Keep
+the secret out of shell history and logs.
Verify the production R2 bucket has a lifecycle rule expiring the
`dataforseo-cache/` prefix (prod lifecycle rules are dashboard-managed). The
diff --git a/knip.jsonc b/knip.jsonc
index 63dfbb3e..9ac98153 100644
--- a/knip.jsonc
+++ b/knip.jsonc
@@ -40,6 +40,8 @@
"!.claude/**",
],
"ignore": ["drizzle/remote-d1.config.ts"],
+ // GitHub CLI, used by deploy:prod; installed system-wide, not via npm
+ "ignoreBinaries": ["gh"],
// Disable Drizzle plugin - it tries to load drizzle/sqlite.config.ts which imports cloudflare:workers
"drizzle": false,
"ignoreDependencies": [
diff --git a/package.json b/package.json
index f607dfae..a71f6d7d 100644
--- a/package.json
+++ b/package.json
@@ -15,7 +15,7 @@
"preview": "npm run build && vite preview --port 3001",
"deploy": "npm run db:migrate:prod && npm run build && wrangler deploy -c dist/open_seo_audit/wrangler.json && wrangler deploy",
"deploy:selfhost": "node scripts/selfhost-deploy-preflight.mjs && vite build --mode selfhost && tsc --noEmit && pnpm alchemy deploy deploy/alchemy/alchemy.run.ts --env-file .env.selfhost --stage selfhost",
- "deploy:postgres": "npm run db:migrate:pg && npm run build && pnpm alchemy deploy deploy/alchemy/alchemy.run.ts --env-file .env.production --stage hosted-prod --adopt",
+ "deploy:prod": "gh workflow run deploy-production.yml --repo bensenescu/open-seo --ref main",
"deploy:preview": "vite build --mode preview && pnpm alchemy deploy deploy/alchemy/alchemy.run.ts --env-file .env.preview",
"preview:access": "pnpm alchemy deploy deploy/alchemy/alchemy.preview-access.run.ts --env-file .env.preview --stage preview-access --adopt",
"alchemy": "NODE_OPTIONS=\"$NODE_OPTIONS --experimental-strip-types\" alchemy",