Open source alternative to Semrush and Ahrefs
Alchemy preview deployments
OpenSEO preview stages use isolated Cloudflare resources and a shared, Alchemy-managed Cloudflare Access boundary.
Security model
- Preview Workers are named
open-seo-<stage>and served fromopen-seo-<stage>.<WORKERS_SUBDOMAIN>. - One persistent Access application protects
open-seo-*.<WORKERS_SUBDOMAIN>before any preview Worker exists. - Production uses the unsuffixed
open-seoWorker onapp.openseo.soandwww.app.openseo.so. It does not match the preview wildcard and is not placed behind preview Access. - A separate persistent Alchemy stack manages the shared Access boundary. A failed preview deploy or teardown therefore cannot remove the gate protecting other previews.
pnpm preview:accessdeploys/reconciles the persistent Access stack — one-time setup, safe to re-run. Every CI deploy then verifies the real HTTP challenge (a curl check inpr-preview.yml, with retries for propagation delays) before commenting a URL, so a missing gate fails the job. A preview that answers without the challenge is public — destroy the stage (pnpm destroy:preview); a merely unreachable one can stay, as it still sits behind the wildcard application.
Credentials
Alchemy manages Cloudflare credentials itself — nothing credential-shaped goes in the env files.
- Locally, run
pnpm alchemy loginonce. Answer yes to Customize OAuth scopes? and enableaccess:writeon top of the defaults (the preview Access gate needs it; addquery_cache:writetoo if you will deploy production — Hyperdrive). The credential is stored globally, and later runs — including non-interactive ones — reuse it silently. - State lives in the account's Cloudflare state store (an
alchemy-state-storeWorker with embedded SQLite), shared by every machine and CI — provision it once withpnpm alchemy cloudflare bootstrap. It mints an auth token and encryption key into the account Secrets Store; local runs cache credentials under~/.alchemy/. - In GitHub Actions, the runner's
CIenv makes alchemy readCLOUDFLARE_API_TOKENandCLOUDFLARE_ACCOUNT_IDfrom the environment (repo secrets), and resolve the state-store token from the Secrets Store on every run. The token needs write access to Workers Scripts, KV, D1, R2, and Workflows, plus Secrets Store read and Account Settings read (both used by alchemy's state-store login, which fetches its token through a temporary edge-preview worker). CI never touches Access — the gate is one-time local setup.
Cloudflare Access configuration
The persistent Access stack creates a self-hosted application with this public hostname:
open-seo-*.your-subdomain.workers.dev
Use the account's Workers subdomain shown under Workers & Pages, not the
Zero Trust team domain. Set that full value in .env.preview as
WORKERS_SUBDOMAIN. Preview URLs derive from it as
https://open-seo-<stage>.<WORKERS_SUBDOMAIN> — hosted previews use that as
BETTER_AUTH_URL, and CI's verify step probes it; a wrong value fails the
check. Previews in local_noauth or cloudflare_access mode deploy without
it, since nothing reads BETTER_AUTH_URL there; password stages read the
subdomain from the account when it is unset.
Set ACCESS_ALLOWED_EMAILS to the exact comma-separated emails that may open
previews:
[email protected]
pnpm preview:access deploys the persistent Access stack. It always uses
--adopt, so it can recover matching infrastructure if local Alchemy state is
lost — safe to re-run any time. Normal preview teardown only destroys the
requested application stage and cannot touch the Access stack.
Local preview
pnpm alchemy login # once — see Credentials above
cp deploy/.env.preview.example .env.preview
pnpm preview:access # once — the shared Access gate (safe to re-run)
pnpm deploy:preview --stage manual-preview --yes
deploy:preview builds with Vite's preview mode (--mode preview loads
.env.preview into the client bundle) and runs alchemy deploy against
.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: 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
everyone allowed through the gate shares one auto-created admin account — set
AUTH_MODE=hosted in .env.preview (see the example file) to exercise the
real sign-up flow instead.
Destroy the stage (state is shared via the Cloudflare state store, so any machine with credentials can do this):
pnpm destroy:preview --stage manual-preview --yes
CI
.github/workflows/pr-preview.yml deploys stage pr-<n> for every
private-repo PR (then verifies the Access challenge before commenting the
URL) and destroys it when the PR closes, running the same commands as local
deploys. State is shared through the Cloudflare state store, so CI runs and
local machines see the same stages — a straggler can always be destroyed
locally with pnpm destroy:preview --stage pr-<n> --yes.
Public-mirror PRs
External (every-app/open-seo) PRs never deploy from CI — fork code must not
run with deploy secrets. Preview one locally instead: the fork's code only
BUILDS, in a detached sibling worktree, and the deploy runs from this trusted
checkout's alchemy stack against the fork's dist/. The fork's own deploy
scripts never execute (fork PRs may also predate the alchemy setup entirely).
Read the PR's diff for the build-executable surface first — package.json,
the lockfile, vite.config*, scripts/, patches/, .npmrc — because
building executes the fork's config code on your machine with .env.preview
available.
git fetch https://github.com/every-app/open-seo.git pull/<pr>/head
git worktree add --detach ../open-seo-pub-<pr> FETCH_HEAD
cp .env.preview ../open-seo-pub-<pr>/
(cd ../open-seo-pub-<pr> && pnpm install --frozen-lockfile && pnpm exec vite build --mode preview)
rm -rf dist && cp -R ../open-seo-pub-<pr>/dist dist
git worktree remove --force ../open-seo-pub-<pr>
pnpm alchemy deploy --env-file .env.preview --stage pub-<pr> --yes
Verify the preview redirects to the Access login before sharing its URL. Destroy the stage whenever the PR is done:
pnpm destroy:preview --stage pub-<pr> --yes
Production
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. Local preview deployment commands do
not deploy production.
Self-hosting on Cloudflare
Self-hosters deploy the same stack under the fixed selfhost stage (via
pnpm deploy:selfhost — no stage to pass) with their own env file: Alchemy
provisions fresh D1/KV/R2/workflows by name (D1 is the database — no
Postgres/Hyperdrive), plus the Cloudflare Access application
gating the worker (AUTH_MODE=cloudflare_access +
ACCESS_ALLOWED_EMAILS; resolveSelfHostAccess in deploy/alchemy/alchemy.run.ts derives
TEAM_DOMAIN/POLICY_AUD, or accepts them explicitly for a hand-managed
application). The preview Access wildcard and PR workflow are
OpenSEO-specific and not required. The walkthrough lives in
docs/SELF_HOSTING_CLOUDFLARE.md.