Where to Find OpenSEO Documentation: A Complete Guide to the every-app/open-seo Repository

TLDR: OpenSEO documentation is maintained in the repository's README.md, the docs/ directory, and the official website at openseo.so/docs.

OpenSEO is an open-source SEO analytics platform hosted at every-app/open-seo. The project maintains comprehensive technical documentation across multiple locations within the repository, from quick-start guides to detailed deployment instructions for self-hosting scenarios.

Repository Documentation Structure

The primary documentation for OpenSEO lives in two main locations within the source code: the README.md file for high-level project information, and the docs/ directory for technical implementation guides.

README.md – Project Overview

The README.md serves as the essential first stop for new users. According to the every-app/open-seo source code, this file contains the project description, links to the hosted version, main SEO workflows, cost information, and navigation links to deeper technical documentation. It provides the bridge between the public-facing project description and the technical implementation details.

The docs/ Directory

The docs/ folder houses the complete technical reference for the project. This directory contains specialized guides covering self-hosting options, API configuration, and development workflows. All documentation is version-controlled in the main branch, ensuring the GitHub blob URLs always reflect the current state of the project.

Self-Hosting Documentation

OpenSEO provides detailed guides for deploying your own instance, supporting both Docker and Cloudflare Workers infrastructures.

Docker Deployment Guide

The docs/SELF_HOSTING_DOCKER.md file contains prerequisites, environment variable setup, telemetry controls, image pinning strategies, and troubleshooting steps. To start a Docker-based instance according to the official documentation:

# Copy the example environment file and start the container

cp .env.example .env
docker compose up -d

This guide covers production deployment considerations and explains how to pin specific image versions for stability.

Cloudflare Workers Deployment

For serverless deployments, docs/SELF_HOSTING_CLOUDFLARE.md provides Cloudflare-specific configuration guidance. This includes Cloudflare Access configuration, KV bindings setup, deployment commands, and advanced infrastructure patterns. This guide targets users familiar with the Cloudflare ecosystem who want to deploy without managing containers.

API Configuration and Development

DataForSEO API Key Setup

The docs/DATAFORSEO_API_KEY.md file explains how to encode and supply the required API credentials. The documentation specifies that you must provide a Base64-encoded email:password string and place it in the appropriate environment variable or configuration file.

Local Development Environment

The docs/LOCAL_DEVELOPMENT.md guide covers complete development setup, dependency installation, and running the Vite development server. To set up locally:

pnpm install          # install dependencies

pnpm dev              # start Vite dev server (http://localhost:5173)

This file also documents MCP server configuration for local AI agent integration, referencing the specific endpoints and ports used by the application.

Contributing Guidelines

The docs/CONTRIBUTING.md file outlines code style requirements, testing procedures, PR workflow, and linting commands. Review this file before submitting changes to ensure compliance with the project's standards and CI requirements.

Official Website Documentation

Beyond the repository, OpenSEO maintains searchable end-user documentation at openseo.so/docs. This external site hosts the MCP and agent skills reference, API documentation, and example usage patterns that complement the technical guides found in the repository source code.

MCP Integration Example

To interact with OpenSEO programmatically via the Model Context Protocol (MCP) as documented in the repository:

import { createMCPClient } from '@every-app/sdk';

const client = createMCPClient({
  baseUrl: 'http://localhost:3001',   // or your deployed URL
  apiKey: process.env.DATAFORSEO_API_KEY,
});

await client.project.list(); // example MCP call

This pattern is referenced in the README.md and docs/LOCAL_DEVELOPMENT.md files for developers integrating OpenSEO into AI agent workflows.

Summary

• Primary locations: OpenSEO documentation exists in README.md, the docs/ directory, and at openseo.so/docs
• Self-hosting: Docker instructions are in docs/SELF_HOSTING_DOCKER.md and Cloudflare Workers in docs/SELF_HOSTING_CLOUDFLARE.md
• API setup: Base64-encoded credential formatting is documented in docs/DATAFORSEO_API_KEY.md
• Development: Local setup uses pnpm workflows documented in docs/LOCAL_DEVELOPMENT.md
• Contributing: Standards and workflows are defined in docs/CONTRIBUTING.md
• Source files: Core application code resides in src/ with database schemas in drizzle-pg/

Frequently Asked Questions

Is the OpenSEO documentation available offline?

Yes. Since every file in the docs/ directory and the README.md are version-controlled in the every-app/open-seo repository, you can access the complete documentation offline by cloning the repository. All guides including Docker setup, Cloudflare deployment, and API configuration are available as markdown files that render locally in any text editor or markdown viewer.

What is the difference between the repository docs and the official website?

The repository documentation focuses on technical implementation, self-hosting instructions, and development setup for contributors and operators. The official website at openseo.so/docs provides end-user documentation, searchable reference materials for the MCP and agent skills, and example usage patterns designed for SEO practitioners and non-technical users who use the hosted version.

Do I need to read the contributing guide before self-hosting OpenSEO?

No, docs/CONTRIBUTING.md is only necessary if you plan to modify the source code or submit pull requests. For self-hosting purposes, focus on docs/SELF_HOSTING_DOCKER.md or docs/SELF_HOSTING_CLOUDFLARE.md depending on your infrastructure, and docs/DATAFORSEO_API_KEY.md for API authentication requirements. The package.json file contains the available scripts for building and running the application.

Where do I find the environment variable templates for local development?

The environment variable templates are referenced in docs/LOCAL_DEVELOPMENT.md and the Docker-specific guide assumes an .env.example file exists in the repository root. Copy this file to .env and populate it with your DataForSEO API credentials formatted according to the instructions in docs/DATAFORSEO_API_KEY.md.

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