What Is the Purpose of the Docs Folder in the Open-SEO Repository?

The docs folder in the every-app/open-seo repository serves as the centralized, version-controlled documentation hub that ships with the application, providing self-hosting guides, development instructions, and technical specifications that power both the README references and the in-app Help interface.

The every-app/open-seo repository maintains all user-facing documentation inside the docs directory at the repository root. This architectural decision ensures that every release of the Open-SEO application includes matching documentation, eliminating version drift between code and guides. The markdown files stored here cover everything from Docker deployment to local development workflows, all tightly coupled with the React/Vite frontend that renders this content directly to end users.

Self-Hosting Documentation

The primary consumer of the docs folder is the self-hosting community. When users deploy Open-SEO to their own infrastructure, they rely on step-by-step instructions stored in version-controlled markdown rather than external wikis.

Docker Deployment

The docs/SELF_HOSTING_DOCKER.md file contains the canonical guide for containerized deployments. This document explains the Docker Compose configuration, required environment variables, and common operational commands. Because this file lives in the repository root under docs/, the CI pipeline can validate that all referenced paths and environment variables remain accurate as the codebase evolves.

Cloudflare Workers Setup

For serverless deployments, docs/SELF_HOSTING_CLOUDFLARE.md provides the Deploy button workflow, Wrangler CLI instructions, and secret management procedures. This guide ensures that users running Open-SEO on Cloudflare's edge network understand the specific authentication and configuration requirements for that platform.

Google Search Console Integration

Optional OAuth integration with Google Search Console is documented in docs/SELF_HOSTING_GOOGLE_SEARCH_CONSOLE.md. This file covers the GSC OAuth flow setup, credential configuration, and verification steps necessary to enable search analytics features in self-hosted instances.

Development and Maintenance Guides

Beyond deployment instructions, the docs folder houses operational knowledge for developers and maintainers.

Local Development Workflow

The docs/LOCAL_DEVELOPMENT.md file details the pnpm toolchain setup, dependency installation, and local UI execution. This guide targets contributors who need to run the React/Vite application locally before submitting changes to the core codebase.

Migration Cleanup Procedures

When database migrations fail or duplicate default projects appear, docs/default-project-cleanup.md provides the one-off script references and manual procedures required to restore data integrity. This operational document acts as a runbook for administrators handling edge-case migration failures.

Contributor Guidelines

The docs/MAINTAINERS.md file establishes contribution guidelines, code-of-conduct policies, and release-note procedures for core contributors. This document governs the social and technical contract for developers with commit access to the every-app/open-seo repository.

Technical Specifications and Architecture

The docs directory also stores design specifications that inform implementation decisions. The docs/self-host-auth-mode-spec.md file defines authentication modes and security considerations that feed into both the application code and the generated user documentation. Storing these specifications alongside operational guides ensures that architectural decisions remain transparent and auditable.

Integration with the Application UI

Unlike traditional documentation sites that exist separately from application code, the Open-SEO React frontend imports content directly from the docs folder. The in-app Help section renders markdown files such as SELF_HOSTING_DOCKER.md directly within the UI, creating a seamless support experience. This tight coupling means that when developers update docs/LOCAL_DEVELOPMENT.md, those changes immediately reflect in the application's help interface without requiring a separate documentation build step.

The following React component demonstrates how the UI links to documentation stored in the repository:

import { Link } from 'react-router-dom';

export const SetupHelp = () => (
  <section>
    <h2>Self-hosting guide</h2>
    <p>
      Follow the official Docker instructions:
      <Link to="/docs/SELF_HOSTING_DOCKER.md">Docker Self-Hosting</Link>
    </p>
  </section>
);

CI/CD Validation and Link Integrity

The every-app/open-seo repository treats documentation as code, subjecting markdown files to the same quality controls as TypeScript and React components. The CI pipeline validates markdown links during builds, ensuring that references to docs/SELF_HOSTING_CLOUDFLARE.md or docs/MAINTAINERS.md remain valid across pull requests.

The following package.json script configuration enables automated markdown link checking:

{
  "scripts": {
    "check-docs": "markdown-link-check https://github.com/every-app/open-seo/blob/main/docs/*.md"
  }
}

Additionally, deployment scripts can programmatically construct documentation URLs:

DOC_URL="https://github.com/every-app/open-seo/blob/main/docs/SELF_HOSTING_DOCKER.md"
echo "Documentation for Docker self-hosting: $DOC_URL"

Summary

• The docs folder serves as the single source of truth for all Open-SEO user-facing documentation, versioned alongside application code.
• Key self-hosting guides include SELF_HOSTING_DOCKER.md, SELF_HOSTING_CLOUDFLARE.md, and SELF_HOSTING_GOOGLE_SEARCH_CONSOLE.md.
• Development documentation covers local setup in LOCAL_DEVELOPMENT.md and contribution policies in MAINTAINERS.md.
• The React/Vite UI renders documentation directly from this folder, enabling in-app Help sections without separate build steps.
• CI pipelines validate markdown links and ensure documentation accuracy remains synchronized with codebase changes.

Frequently Asked Questions

What is the purpose of the docs folder in the Open-SEO repository?

The docs folder provides the centralized location for all user-facing documentation that ships with every release of Open-SEO. It contains self-hosting guides, development instructions, technical specifications, and operational runbooks that power both the GitHub README references and the React application's in-app Help system.

How does Open-SEO use documentation from the docs folder in the UI?

The React/Vite frontend imports and renders markdown files directly from the docs directory, allowing users to view self-hosting instructions and development guides within the application interface. This architectural choice ensures that the help content users see always matches the version of the code they are running, as implemented in the every-app/open-seo repository.

Which file should I read to self-host Open-SEO on Docker?

You should read docs/SELF_HOSTING_DOCKER.md, which explains the Docker Compose configuration, required environment variables, and common management commands. This file is referenced directly from the main README and is validated by the CI pipeline to ensure accuracy with the current release.

Why does Open-SEO store technical specifications in the docs folder?

The repository stores design specifications like docs/self-host-auth-mode-spec.md alongside operational guides to maintain transparency between architectural decisions and user-facing documentation. This co-location ensures that authentication modes, security considerations, and implementation details remain version-controlled and accessible to both developers and advanced users.

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