# How to Configure and Run OpenSEO Locally for Development

> Learn to configure and run OpenSEO locally for development. Follow steps including pnpm setup, database migration, API key configuration, and launching the dev server for efficient local testing with every-app/open-seo.

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

---

**To configure and run OpenSEO locally, enable Corepack to activate pnpm, install dependencies with frozen lockfile, migrate the local Cloudflare D1 database, configure your DataForSEO API key in `.env.local`, and launch the dev server using either `pnpm run dev` or `pnpm dev:agents` for agent-friendly access.**

OpenSEO is a modern TypeScript-based SEO platform that uses Node.js 20+ and Cloudflare D1 (SQLite) for local development. Configuring the project requires specific environment variables for external APIs and authentication modes that mirror production while enabling rapid iteration. This guide walks through the exact steps to get a fully functional instance running locally, based on the official source code in the `every-app/open-seo` repository.

## Prerequisites and System Requirements

Before cloning the repository, ensure your environment meets the baseline requirements. OpenSEO requires **Node.js 20 or higher** and uses **pnpm** (version `10.30.1` as pinned in [`package.json`](https://github.com/every-app/open-seo/blob/main/package.json)) as its package manager.

You must also obtain a **DataForSEO** account and generate a base-64 encoded token from your `login:password` credentials. This API key powers the platform's SEO data retrieval capabilities.

## Project Setup and Package Manager Activation

The repository uses Corepack to enforce the exact pnpm version recorded in [`package.json`](https://github.com/every-app/open-seo/blob/main/package.json), preventing dependency drift across environments.

First, enable Corepack to activate the pinned package manager:

```bash
corepack enable

```

Then install dependencies using the frozen lockfile to guarantee exact version matching:

```bash
pnpm install --frozen-lockfile

```

This command respects [`pnpm-lock.yaml`](https://github.com/every-app/open-seo/blob/main/pnpm-lock.yaml) and ensures consistent dependency trees across all developer machines.

## Database Preparation and Migration

OpenSEO defaults to **Cloudflare D1** (SQLite) for local development. Before running the application, you must initialize the local database schema using the provided migration script.

Run the local migration command from the project root:

```bash
pnpm run db:migrate:local

```

This command applies the Drizzle ORM migrations located in `src/db/` to your local D1 instance. You only need to run this once per fresh clone or after schema changes. For PostgreSQL-backed setups, refer to the alternative configuration in [`docs/LOCAL_POSTGRES.md`](https://github.com/every-app/open-seo/blob/main/docs/LOCAL_POSTGRES.md).

## Environment Configuration

The application relies on environment variables defined in `.env.local`. Copy the example template to create your local configuration:

```bash
cp .env.example .env.local

```

Edit `.env.local` to include your **DataForSEO API key** and authentication mode:

```bash

# Required: Base64-encoded DataForSEO credentials

DATAFORSEO_API_KEY=$(printf 'your_login:your_password' | base64)

# Recommended for local development

AUTH_MODE=local_noauth

```

The `AUTH_MODE` variable controls user validation. Set it to `local_noauth` to bypass authentication and automatically inject an admin user (`admin@localhost`), which is ideal for rapid local development without configuring external identity providers.

## Running the Development Server

OpenSEO provides two distinct methods to start the local development server, defined in [`package.json`](https://github.com/every-app/open-seo/blob/main/package.json).

### Standard Vite Development

For quick UI previews and standard development:

```bash
pnpm run dev

```

This launches the Vite development server in standard mode, suitable for manual browser testing.

### Agent-Friendly Development Mode

For AI agent integration and enhanced logging:

```bash
mkdir -p .logs
pnpm dev:agents

```

This command starts the application through **portless**, a zero-config reverse proxy, and streams logs to `.logs/dev-server.log`. The server runs at `http://open-seo.localhost:1355` and automatically prefixes URLs with the current git branch name when working in worktrees, making it the recommended entry point for automated tooling and agent-based workflows according to [`docs/LOCAL_DEVELOPMENT.md`](https://github.com/every-app/open-seo/blob/main/docs/LOCAL_DEVELOPMENT.md).

## Understanding Authentication Modes

The `AUTH_MODE` environment variable determines how OpenSEO validates user sessions. The source code supports three distinct modes:

- **`local_noauth`** – Bypasses authentication entirely, injecting a mock admin user. This is the default recommendation for local development to eliminate external dependency requirements.
- **`cloudflare_access`** – Validates Cloudflare Access JWTs, used in production deployments behind Cloudflare Zero Trust.
- **`hosted`** – Enables BetterAuth email/password authentication flow, requiring additional secrets for email providers and callback URLs.

Development scripts do not automatically set `AUTH_MODE`, so you must explicitly declare it in `.env.local` to experiment with non-default authentication flows.

## Docker Self-Hosting Alternative

For containerized local development, OpenSEO includes a Docker Compose configuration:

```bash
docker compose up -d

```

The [`docker-compose.yaml`](https://github.com/every-app/open-seo/blob/main/docker-compose.yaml) automatically sets `AUTH_MODE=local_noauth`, providing a zero-config containerized environment that persists data and respects the same environment variable patterns as the native Node.js setup.

## Summary

- **Enable Corepack** (`corepack enable`) to activate the pinned pnpm version `10.30.1` declared in [`package.json`](https://github.com/every-app/open-seo/blob/main/package.json).
- **Install dependencies** using `pnpm install --frozen-lockfile` to ensure reproducible builds.
- **Initialize the database** by running `pnpm run db:migrate:local` to set up the Cloudflare D1 schema.
- **Configure environment variables** in `.env.local`, including a base64-encoded `DATAFORSEO_API_KEY` and `AUTH_MODE=local_noauth`.
- **Start the server** using either `pnpm run dev` for standard development or `pnpm dev:agents` for AI-agent-friendly access at `http://open-seo.localhost:1355`.

## Frequently Asked Questions

### What Node.js version does OpenSEO require?

OpenSEO requires **Node.js 20 or higher**. The project uses modern JavaScript features and relies on Corepack (bundled with Node.js 24, available separately in Node.js 20) to manage the pnpm package manager version.

### Why does my DataForSEO API key need to be base64 encoded?

The DataForSEO API uses HTTP Basic Authentication, which requires the `login:password` string to be **base64 encoded** before being sent in the Authorization header. The application expects this pre-encoded value in the `DATAFORSEO_API_KEY` environment variable to match the API's authentication protocol.

### Can I use PostgreSQL instead of Cloudflare D1 for local development?

Yes. While Cloudflare D1 is the default for local development, the repository includes PostgreSQL configuration instructions in [`docs/LOCAL_POSTGRES.md`](https://github.com/every-app/open-seo/blob/main/docs/LOCAL_POSTGRES.md). The Drizzle ORM migrations in `src/db/` support both SQLite (D1) and PostgreSQL dialects.

### What is the difference between `pnpm run dev` and `pnpm dev:agents`?

**`pnpm run dev`** starts the standard Vite development server for manual browser testing. **`pnpm dev:agents`** launches the application through portless with automatic branch-based URL prefixing and logs streamed to `.logs/dev-server.log`, specifically designed for AI agent integration and automated development workflows.