How to Run a Local Development Environment for OpenSEO: Complete Setup Guide

To run a local development environment for OpenSEO, install Node 20+ and pnpm, execute pnpm install and pnpm run db:migrate:local, configure your .env.local file with Base64-encoded DataForSEO credentials, then launch the server with pnpm run dev or pnpm dev:agents for enhanced logging.

Setting up a local development environment for OpenSEO requires configuring a Node 20+ stack with pnpm as the package manager and preparing a local SQLite database compatible with Cloudflare D1. The every-app/open-seo repository provides npm scripts in package.json that automate database migrations and Vite server startup. This guide walks through the exact commands and configuration files needed to get the dev server running at http://open-seo.localhost:1355.

Prerequisites and Initial Setup

OpenSEO depends on modern Node.js features and requires specific tooling before installation.

Install Node 20+ and pnpm

Ensure your system runs Node.js version 20 or higher. Install pnpm globally to handle workspace dependencies:

npm i -g pnpm@10

Clone the repository and install all workspace packages:

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

The install command processes dependencies defined in package.json, which contains scripts for "dev": "vite dev" and other essential commands【/cache/repos/github.com/every-app/open-seo/main/package.json#L8-L13】.

Database Migration

OpenSEO uses a Cloudflare D1-compatible SQLite database for local development. You must initialize this database before running the application.

Run the local migration script once after cloning:

pnpm run db:migrate:local

This script executes wrangler d1 migrations apply DB --local as defined in package.json under the "db:migrate:local" key【/cache/repos/github.com/every-app/open-seo/main/package.json#L24-L26】. The command creates and configures the local SQLite file that stores application data during development.

Environment Configuration

Create a local environment file to store API credentials and configuration variables:

cp .env.example .env.local

Edit .env.local to add your DataForSEO API key. This value must be Base64-encoded in the format login:password:

# Generate the Base64 string

printf '%s' 'mylogin:mypassword' | base64

# Output: bXlsb2dpbjpteXBhc3N3b3Jk

Paste the result into .env.local:

DATAFORSEO_API_KEY=bXlsb2dpbjpteXBhc3N3b3Jk

The documentation in docs/LOCAL_DEVELOPMENT.md details this requirement on lines 18-24, emphasizing the Base64 encoding requirement for the DataForSEO integration【/cache/repos/github.com/every-app/open-seo/main/docs/LOCAL_DEVELOPMENT.md#L18-L24】.

Starting the Development Server

OpenSEO offers two modes for running the local development server: standard Vite mode and the recommended agents mode with enhanced logging.

Standard Development Server

Run the basic Vite development server:

pnpm run dev

This executes vite dev directly and serves the application on the default port.

Agents Mode (Recommended)

For a superior development experience with stable hostnames and file logging, use the agents script:

pnpm dev:agents

This command expands to mkdir -p .logs && portless run vite dev 2>&1 | tee .logs/dev-server.log, which creates a .logs directory and streams output to .logs/dev-server.log while exposing the app at http://open-seo.localhost:1355【/cache/repos/github.com/every-app/open-seo/main/package.json#L11-L13】. The portless utility adds a stable hostname and eliminates port conflicts, as documented in docs/LOCAL_DEVELOPMENT.md lines 27-38【/cache/repos/github.com/every-app/open-seo/main/docs/LOCAL_DEVELOPMENT.md#L27-L38】.

When using git worktrees, the server automatically maps to http://<branch>.open-seo.localhost:1355.

Authentication Mode Configuration

By default, local development sets AUTH_MODE=local_noauth, bypassing Cloudflare Access checks for immediate access.

To test Cloudflare Access integration locally, override the authentication mode:

AUTH_MODE=cloudflare_access pnpm run dev

The docs/LOCAL_DEVELOPMENT.md file on lines 58-66 describes the supported authentication modes and when to use each configuration【/cache/repos/github.com/every-app/open-seo/main/docs/LOCAL_DEVELOPMENT.md#L58-L66】.

Key Configuration Files

Understanding these files helps troubleshoot and extend your local environment:

• docs/LOCAL_DEVELOPMENT.md – Contains the complete official documentation for prerequisites, database setup, and server commands.
• package.json – Defines all npm scripts including dev, dev:agents, and db:migrate:local.
• .env.example – Template showing required environment variables, particularly DATAFORSEO_API_KEY.
• vite.config.ts – Configures the Vite development server, including proxy settings for portless integration.

Summary

• Install prerequisites: Node 20+ and pnpm 10 are required before cloning the every-app/open-seo repository.
• Initialize the database: Run pnpm run db:migrate:local once to apply D1-style migrations to the local SQLite database.
• Configure environment: Copy .env.example to .env.local and set DATAFORSEO_API_KEY as a Base64-encoded string.
• Start the server: Use pnpm run dev for standard mode or pnpm dev:agents for stable hostnames with logging.
• Manage auth: Default mode bypasses authentication; set AUTH_MODE=cloudflare_access to test access controls.

Frequently Asked Questions

What Node.js version is required for OpenSEO development?

OpenSEO requires Node.js 20 or higher. The project uses modern JavaScript features and the Vite build tool, which depend on recent Node APIs. Install pnpm globally with npm i -g pnpm@10 before running pnpm install.

How do I encode my DataForSEO credentials for the environment file?

DataForSEO credentials must be Base64-encoded in the format login:password. Use the command printf '%s' 'mylogin:mypassword' | base64 in your terminal to generate the encoded string, then paste the result into .env.local as DATAFORSEO_API_KEY=encoded_value.

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

pnpm run dev starts a standard Vite development server, while pnpm dev:agents uses portless to create a stable hostname (open-seo.localhost:1355) and logs output to .logs/dev-server.log. The agents mode is recommended for consistent local development and debugging.

Can I test Cloudflare Access authentication locally?

Yes, though the default AUTH_MODE=local_noauth bypasses authentication. To test Cloudflare Access, start the server with AUTH_MODE=cloudflare_access pnpm run dev after configuring the appropriate access policies in your Cloudflare dashboard.

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