Open source alternative to Semrush and Ahrefs
TypeScript backlink-analysisgoogle-search-console-mcpkeyword-researchmcpseoseo-agentseo-auditseo-automationseo-skillsseo-toolssite-audit
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.ymlnew file mode 100644index 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/.gitignoreindex 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.outputdiff --git a/deploy/.env.production.example b/deploy/.env.production.exampledeleted file mode 100644index 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.tsindex 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.mdindex 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 defaultper-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 Accesschallenge, 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 Cloudflarediff --git a/docs/maintainers/production-deployment.md b/docs/maintainers/production-deployment.mdnew file mode 100644index 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.mdindex 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** andwrites 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 silentlytruncated yet reported success; reading tables over the API avoids that wholeclass 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, checkdiff --git a/docs/maintainers/runbooks/d1-to-postgres-simple.md b/docs/maintainers/runbooks/d1-to-postgres-simple.mdindex 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 androllback — 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, thsmoke-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 thediff --git a/docs/maintainers/runbooks/gdpr-erasure.md b/docs/maintainers/runbooks/gdpr-erasure.mdindex 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 asingle HMAC-authenticated endpoint at `/api/internal/gdpr-erasure/storage`; theendpoint 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). Thediff --git a/knip.jsonc b/knip.jsoncindex 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.jsonindex 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",