Open-SEO Deployment Strategy: Docker vs Cloudflare Workers Explained

Open-SEO supports two mutually exclusive self-hosting modes: Docker containers for local development and personal hosting, and Cloudflare Workers for production-grade edge deployment with automatic global scaling.

The open-source SEO platform Open-SEO (available at every-app/open-seo) offers flexible deployment strategies designed for different operational needs. Whether you need a quick local instance for development or a globally distributed production environment, the deployment strategy for open-seo accommodates both scenarios using the same TypeScript codebase but different packaging approaches. Both modes share identical source files; only the build target and environment configuration differ.

Docker Deployment Strategy

The Docker deployment strategy packages Open-SEO as a containerized Node.js application suitable for local machines, private servers, or CI environments. This approach uses AUTH_MODE=local_noauth and requires manual security configuration if exposed to the internet.

Container Image Configuration

By default, the compose.yaml file pulls the pre-built public image ghcr.io/every-app/open-seo:latest from GitHub Container Registry. For local code modifications, you can build a custom image using Dockerfile.selfhost and specify it via the OPEN_SEO_IMAGE environment variable.

# Build custom image from source

docker build -f Dockerfile.selfhost -t open-seo:local .

Environment and Authentication

Docker deployments read configuration from a .env file, with values forwarded to the Worker runtime via CLOUDFLARE_INCLUDE_PROCESS_ENV=true as defined in compose.yaml. Critical variables include DATAFORSEO_API_KEY (base64-encoded email:password), optional PORT, ALLOWED_HOST, and OPEN_SEO_IMAGE for version pinning.

When running in Docker, AUTH_MODE=local_noauth automatically creates a single admin user (admin@localhost). According to docs/SELF_HOSTING_DOCKER.md, if you expose this container to the internet, you must protect it behind a reverse proxy or secure tunnel.

Docker Workflow

The standard deployment sequence uses Docker Compose:

# 1. Copy environment template and configure secrets

cp .env.example .env

# Edit .env to set DATAFORSEO_API_KEY=base64(email:password)

# 2. Start the services

docker compose up -d

# 3. Restart after code changes

docker compose up -d open-seo

Cloudflare Workers Deployment Strategy

The Cloudflare Workers deployment strategy compiles the application for Cloudflare's edge network, utilizing KV for caching, D1 for the database, and R2 for object storage. This provides zero-ops scaling and global distribution.

Automated Deployment

A "Deploy to Cloudflare" button in the repository automates resource creation, provisioning KV namespaces, D1 databases, R2 buckets, and the Worker binding in a single operation.

Manual Wrangler Deployment

If automatic deployment fails (for example, when KV namespaces already exist), manual deployment using Wrangler CLI is required. This involves editing wrangler.jsonc to include your specific resource IDs:

# Create required Cloudflare resources

pnpm exec wrangler kv namespace create open-seo-YOUR_SUFFIX
pnpm exec wrangler kv namespace create open-seo-oauth-YOUR_SUFFIX
pnpm exec wrangler d1 create open-seo-YOUR_SUFFIX
pnpm exec wrangler r2 bucket create open-seo-YOUR_SUFFIX

After creating resources, populate wrangler.jsonc with the generated IDs while preserving the binding names exactly as specified in docs/SELF_HOSTING_CLOUDFLARE.md.

Secret Management

Three Worker secrets must be configured using Wrangler:

• POLICY_AUD - Cloudflare Access "Audience" token
• TEAM_DOMAIN - JWKS URL domain
• DATAFORSEO_API_KEY - Base64-encoded DataForSEO credentials

pnpm exec wrangler secret put TEAM_DOMAIN
pnpm exec wrangler secret put POLICY_AUD
pnpm exec wrangler secret put DATAFORSEO_API_KEY

R2 Cache Lifecycle

As documented in docs/SELF_HOSTING_CLOUDFLARE.md, an optional lifecycle rule automatically purges cached DataForSEO responses from R2 after 7 days, preventing storage bloat.

Updating Cloudflare Deployments

Because wrangler.jsonc stores Cloudflare resource IDs, updates require preserving this file while pulling new code:

git remote add upstream https://github.com/every-app/open-seo.git
git fetch upstream
cp wrangler.jsonc wrangler.local.backup.jsonc
git checkout main
git reset --hard upstream/main
cp wrangler.local.backup.jsonc wrangler.jsonc
git add wrangler.jsonc
git commit -m "restore Cloudflare settings"
git push --force-with-lease origin main

Choosing Between Deployment Strategies

Select your deployment strategy based on operational requirements:

• Docker is optimal for local development, CI/CD testing, or single-machine personal instances where you manage your own infrastructure and reverse proxy.
• Cloudflare Workers is the production-grade choice, offering global edge latency, automatic scaling, and managed storage (KV/D1/R2) without server maintenance.

Both strategies execute identical business logic; only the runtime environment and packaging differ.

Summary

• Open-SEO offers two deployment modes: Docker containers and Cloudflare Workers, sharing the same TypeScript source but differing in target runtime.
• Docker deployment uses Dockerfile.selfhost and compose.yaml, runs with AUTH_MODE=local_noauth, and requires manual security hardening for internet exposure.
• Cloudflare deployment uses wrangler.jsonc, requires KV/D1/R2 bindings, and needs three secrets: POLICY_AUD, TEAM_DOMAIN, and DATAFORSEO_API_KEY.
• Docker suits development and private hosting; Cloudflare Workers suit global production workloads.
• Always use base64-encoded credentials for DATAFORSEO_API_KEY regardless of deployment mode.

Frequently Asked Questions

What is the recommended deployment strategy for open-seo production use?

Cloudflare Workers is the recommended production deployment strategy according to the every-app/open-seo source code. It provides automatic global distribution, zero server maintenance, and built-in support for KV caching, D1 databases, and R2 storage. Docker is explicitly intended for local development and testing.

Can I run open-seo locally without Cloudflare?

Yes, the Docker deployment strategy allows entirely local operation without Cloudflare dependencies. Configure your .env file with DATAFORSEO_API_KEY and run docker compose up -d using the compose.yaml file. This creates a self-contained instance accessible only via localhost unless you add a reverse proxy.

How do I update an existing Cloudflare Workers deployment?

Preserve your wrangler.jsonc file (which contains resource IDs), pull the latest upstream code from every-app/open-seo, restore your configuration file, and force-push to your fork. This workflow maintains your Cloudflare bindings while updating the application code.

What environment variables are required for Docker deployment?

The minimal required variable is DATAFORSEO_API_KEY (base64-encoded email and password). Optional variables include PORT (defaults to 8787), ALLOWED_HOST, and OPEN_SEO_IMAGE for pinning specific container tags. All variables are defined in .env.example and consumed via compose.yaml.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}