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

> Install Open-SEO easily with Docker for local testing or deploy to Cloudflare Workers for scalable production. Get your Open-SEO setup running quickly.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: how-to-guide
- Published: 2026-08-06

---

**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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/web/src/routes/_marketing.tsx)), a TanStack Server backend API (implemented in [`src/server/mcp/transport.test.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.test.ts)), and a database layer configured via [`drizzle.config.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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:

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

2. **Configure environment variables** by copying the example file:

   ```bash
   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:

   ```bash
   docker compose up -d
   ```

   This command reads [`compose.yaml`](https://github.com/every-app/open-seo/blob/main/compose.yaml) to start the API container, database (SQLite by default), and optional telemetry services.

4. **Access the dashboard** at the default local address:

   ```bash
   open http://localhost:3001
   ```

   The documentation in [`docs/SELF_HOSTING_DOCKER.md`](https://github.com/every-app/open-seo/blob/main/docs/SELF_HOSTING_DOCKER.md) confirms the default port is `3001`.

### Custom Configuration Options

- **Custom domain**: Set the `ALLOWED_HOST` environment variable when launching:

  ```bash
  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:

  ```bash
  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`](https://github.com/every-app/open-seo/blob/main/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:

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

2. **Install dependencies** using pnpm:

   ```bash
   pnpm install
   ```

   This command resolves workspaces defined in [`pnpm-workspace.yaml`](https://github.com/every-app/open-seo/blob/main/pnpm-workspace.yaml) across the `web`, `src`, and `badseo` packages.

3. **Configure secrets** using Wrangler:

   ```bash
   pnpm exec wrangler secret put DATAFORSEO_API_KEY
   ```

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

4. **Deploy to Cloudflare**:

   ```bash
   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:

   ```bash
   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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/drizzle.config.ts).
- **Monorepo structure**: All installation methods share the same codebase organized by [`pnpm-workspace.yaml`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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.