Cloudflare Self-Hosting

Host OpenSEO on Cloudflare for internet-facing self-hosting across multiple devices or with your team. It works on Cloudflare's free plan.

This doc covers initial setup with the Deploy to Cloudflare button. Related guides:

Manual deploy with Wrangler: use this if the deploy button fails or you want full control over resources.
Operations: connect the MCP server, update to the latest version, add teammates, telemetry.

1) Deploy from GitHub

Click the deploy button, there are lots of fields on the deploy form, but you only need to do the below steps.

Connect your Git provider (GitHub/GitLab).
Leave the resource naming fields as default unless you have a reason to change them.
Click Create and Deploy.
Wait 1-2 minutes for deployment to finish.

If deploy fails with Cannot provision a KV Namespace with the title "open-seo" because it already exists, use the manual deploy with Wrangler flow instead.

2) Configure authentication and secrets

Create the Access application

In the main Cloudflare dashboard, go to Compute -> Workers & Pages -> your OpenSEO Worker -> Settings -> Domains & Routes. Copy the workers.dev hostname. It looks like open-seo.<your-subdomain>.workers.dev.
Open Cloudflare Zero Trust.
Go to Access controls -> Applications -> Create new application -> Self-hosted and private.
Name the application OpenSEO.
Under Destinations -> Public hostnames, click Switch to custom input and paste the exact workers.dev hostname from step 1. Enter only the hostname, without https:// or a path.
Under Access policies, click Create new policy and configure:
- Policy name: Allow OpenSEO users
- Action: Allow
- Include selector: Emails
- Value: your Cloudflare account email
Do not choose Everyone; it allows anyone to reach the application.
Leave the other policy settings at their defaults, save the policy, then save the application.

Collect the values

POLICY_AUD: in Access controls -> Applications, select Configure on your application, then copy the Application Audience (AUD) Tag from Additional settings.
TEAM_DOMAIN: https://<team-name>.cloudflareaccess.com. Your team name is shown in Zero Trust Settings. Include the https:// prefix.
DATAFORSEO_API_KEY: follow DATAFORSEO_API_KEY.md.

Set them on the Worker

Go to Compute -> Workers & Pages -> your OpenSEO Worker -> Settings -> Variables & Secrets.
Add TEAM_DOMAIN, POLICY_AUD, and DATAFORSEO_API_KEY.

3) Optional: add an R2 lifecycle rule

DataForSEO API responses are cached in R2 under the dataforseo-cache/ prefix. This step is optional, but recommended to automatically clean up expired cache objects:

npx wrangler r2 bucket lifecycle add open-seo dataforseo-cache-expiry dataforseo-cache/ --expire-days 7

If you changed the R2 bucket name during deploy, replace open-seo with your bucket name.

Without a lifecycle rule, cached objects under dataforseo-cache/ will accumulate indefinitely and increase storage costs over time.

4) Validate setup

Open your Worker URL again.
Sign in with Cloudflare Access.
OpenSEO should load after login.

If it doesn't, see Troubleshooting below.

Troubleshooting

https://<your-worker-hostname>/api/health reports runtime configuration checks and database status. For server errors, open the Worker Logs or run pnpm exec wrangler tail.

Next steps

See Operations for connecting MCP clients, updating to the latest OpenSEO version, and giving teammates access.

3.9 KiB Raw Blame History