How to Install Open-SEO: Docker and Cloudflare Workers Setup Guide

Open-SEO can be installed locally using Docker Compose for rapid testing or deployed to Cloudflare Workers for production edge scaling, both utilizing the same unified monorepo codebase managed with pnpm workspaces.

Open-SEO is a modern, full-stack SEO platform developed by the every-app/open-seo repository that supports two distinct self-hosting pathways. Whether you need to run it locally for development or serve it globally at the edge, the installation process leverages shared configuration files including compose.yaml and wrangler.jsonc. This guide explains how to install open-seo using both methods with direct references to the authoritative source files in the codebase.

Installation Methods Overview

Open-SEO’s architecture consists of a Vite-powered React frontend (defined in web/src/routes/_marketing.tsx), a TanStack Server backend API (implemented in src/server/mcp/transport.test.ts), and a database layer configured via drizzle.config.ts. You can deploy this stack using either:

• Docker Compose – Recommended for local development and simple self-hosting
• Cloudflare Workers – Optimized for edge-scaled production deployments

Both methods share the same source code and rely on pnpm-workspace.yaml to manage the monorepo dependencies.

Installing Open-SEO with Docker (Recommended for Local Development)

The Docker pathway packages the frontend, backend, and database into containers defined in compose.yaml, using Dockerfile.selfhost as the base image.

Prerequisites

• Docker Engine and Docker Compose installed
• Git for cloning the repository
• Port 3001 available on your local machine

Step-by-Step Docker Installation

1. Clone the repository to your local machine:

   git clone https://github.com/every-app/open-seo.git
   cd open-seo

2. Configure environment variables by copying the example file:

   cp .env.example .env

   Edit .env to add required secrets such as DATAFORSEO_API_KEY or database credentials.

3. Launch the stack using Docker Compose:

   docker compose up -d

   This command reads compose.yaml to start the API container, database (SQLite by default), and optional telemetry services.

4. Access the dashboard at the default local address:

   open http://localhost:3001

   The documentation in docs/SELF_HOSTING_DOCKER.md confirms the default port is 3001.

Custom Configuration Options

• Custom domain: Set the ALLOWED_HOST environment variable when launching:

  ALLOWED_HOST=example.com docker compose up -d

• Disable telemetry: Add OPENSEO_TELEMETRY_DISABLED=1 or DO_NOT_TRACK=1 to your .env file, then force recreate the container:

  OPENSEO_TELEMETRY_DISABLED=1 docker compose up -d --force-recreate open-seo

• View logs: Run docker compose logs -f to stream container output.

• Stop services: Execute docker compose down to halt the stack.

Deploying Open-SEO to Cloudflare Workers (Production)

The Cloudflare pathway compiles the TanStack Server backend into a Worker using the configuration in wrangler.jsonc, enabling global edge deployment.

Prerequisites

• pnpm package manager installed (the project uses pnpm-workspace.yaml for monorepo management)
• A Cloudflare account with Workers enabled
• (Optional) A fork of the repository for CI/CD integration

Cloudflare Installation Steps

1. Clone your fork of the repository:

   git clone https://github.com/YOUR_GITHUB_USER/open-seo.git
   cd open-seo

2. Install dependencies using pnpm:

   pnpm install

   This command resolves workspaces defined in pnpm-workspace.yaml across the web, src, and badseo packages.

3. Configure secrets using Wrangler:

   pnpm exec wrangler secret put DATAFORSEO_API_KEY

   Secrets are bound according to the rules in wrangler.jsonc.

4. Deploy to Cloudflare:

   pnpm exec wrangler publish

   This builds the project and deploys the Worker to Cloudflare’s edge network.

5. Verify deployment by checking the health endpoint:

   curl https://<YOUR_SUBDOMAIN>.workers.dev/api/health

   The backend exposes this health check route to confirm successful installation.

Environment Configuration Reference

Both installation methods rely on environment variables defined in .env.example:

• DATAFORSEO_API_KEY – Required for SEO data provider integration
• DATABASE_URL – Connection string for PostgreSQL (Cloudflare) or SQLite path (Docker)
• OPENSEO_TELEMETRY_DISABLED – Set to 1 to opt out of analytics

For Docker, these values are loaded from the .env file at runtime. For Cloudflare, use wrangler secret put to encrypt sensitive values at the edge.

Summary

• Two pathways: Install open-seo locally with docker compose up -d (using compose.yaml) or deploy globally via pnpm exec wrangler publish (using wrangler.jsonc).
• Default access: Docker exposes port 3001; Cloudflare Workers use your custom subdomain.
• Database flexibility: SQLite works for Docker local installs, while Cloudflare production deployments typically use D1 or PostgreSQL as configured in drizzle.config.ts.
• Monorepo structure: All installation methods share the same codebase organized by pnpm-workspace.yaml.
• Telemetry control: Disable tracking via environment variables in .env or Docker run commands.

Frequently Asked Questions

What is the default port for Open-SEO when using Docker?

The default port is 3001. After running docker compose up -d, access the dashboard at http://localhost:3001 as documented in docs/SELF_HOSTING_DOCKER.md.

Can I use PostgreSQL instead of SQLite with Open-SEO?

Yes. While the Docker quick-start uses SQLite for simplicity, production deployments (especially on Cloudflare Workers) can configure PostgreSQL or Cloudflare D1 by setting the appropriate DATABASE_URL in your environment variables and updating drizzle.config.ts.

How do I disable telemetry in Open-SEO?

Add OPENSEO_TELEMETRY_DISABLED=1 or DO_NOT_TRACK=1 to your .env file, then restart the container with docker compose up -d --force-recreate open-seo. For Cloudflare, set the secret via wrangler secret put with the same variable name.

What is the difference between the Docker and Cloudflare Workers installation methods?

Docker runs the full stack (frontend, API, and database) in containers on your local machine or server using compose.yaml and Dockerfile.selfhost, making it ideal for local development. Cloudflare Workers deploy only the backend API to Cloudflare’s edge network using wrangler.jsonc, requiring separate hosting for the frontend and database, but offering global low-latency access for production traffic.

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