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

> Find OpenSEO documentation easily. This complete guide directs you to the repository README, docs directory, and official openseo.so/docs website for all your needs.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: documentation
- Published: 2026-07-29

---

**TLDR:** OpenSEO documentation is maintained in the repository's [`README.md`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/README.md) file for high-level project information, and the `docs/` directory for technical implementation guides.

### README.md – Project Overview

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

```bash

# 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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/docs/LOCAL_DEVELOPMENT.md) guide covers complete development setup, dependency installation, and running the Vite development server. To set up locally:

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

```typescript
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`](https://github.com/every-app/open-seo/blob/main/README.md) and [`docs/LOCAL_DEVELOPMENT.md`](https://github.com/every-app/open-seo/blob/main/docs/LOCAL_DEVELOPMENT.md) files for developers integrating OpenSEO into AI agent workflows.

## Summary

- **Primary locations**: OpenSEO documentation exists in [`README.md`](https://github.com/every-app/open-seo/blob/main/README.md), the `docs/` directory, and at **openseo.so/docs**
- **Self-hosting**: Docker instructions are in [`docs/SELF_HOSTING_DOCKER.md`](https://github.com/every-app/open-seo/blob/main/docs/SELF_HOSTING_DOCKER.md) and Cloudflare Workers in [`docs/SELF_HOSTING_CLOUDFLARE.md`](https://github.com/every-app/open-seo/blob/main/docs/SELF_HOSTING_CLOUDFLARE.md)
- **API setup**: Base64-encoded credential formatting is documented in [`docs/DATAFORSEO_API_KEY.md`](https://github.com/every-app/open-seo/blob/main/docs/DATAFORSEO_API_KEY.md)
- **Development**: Local setup uses `pnpm` workflows documented in [`docs/LOCAL_DEVELOPMENT.md`](https://github.com/every-app/open-seo/blob/main/docs/LOCAL_DEVELOPMENT.md)
- **Contributing**: Standards and workflows are defined in [`docs/CONTRIBUTING.md`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/docs/SELF_HOSTING_DOCKER.md) or [`docs/SELF_HOSTING_CLOUDFLARE.md`](https://github.com/every-app/open-seo/blob/main/docs/SELF_HOSTING_CLOUDFLARE.md) depending on your infrastructure, and [`docs/DATAFORSEO_API_KEY.md`](https://github.com/every-app/open-seo/blob/main/docs/DATAFORSEO_API_KEY.md) for API authentication requirements. The [`package.json`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/docs/DATAFORSEO_API_KEY.md).