Self-Hosting Overview

Sitepins is free and open source. You can run the entire platform on your own infrastructure with zero third-party dependencies on hosted SaaS services.

What You Get

Every feature unlocked. The self-hosted build contains no paywalls, plan gates, or billing modules. Everything documented as Pro or Team throughout these docs is immediately available:

Unlimited Scale: No limits on organizations, sites, repositories, collaborators, or storage.
Full Editor Capabilities: Plate rich-text visual editor, raw Markdown editor, and full Monaco code editor.
Real-Time Collaboration: Multi-user editing powered by Yjs CRDTs with live cursor overlays, awareness rosters, and commit notifications.
Interactive Live Preview: Isolated execution of static site generators (Astro, Next.js, Hugo, TanStack, etc.) inside sandbox VMs.
Git Integrations: Native GitHub and GitLab support for branches, pull/merge requests, and direct commits.
Built-in SEO Tools: Live search-result previews, readability analysis, and rule-based audit engines.
AI Integration (BYOK): Multi-provider AI writing and SEO assistance with personal keys stored securely in the browser.
White-Labeling: Fully customizable brand name, logo, legal links, and commit email domains via environment variables.

What You Need

Running Sitepins requires a small set of standard open-source dependencies:

Component	Minimum Requirement	Recommended Production Choice
Node.js	22.0.0 or newer	Node.js 22 or 24 LTS
Package Manager	pnpm 11.0.0 or newer	pnpm 11.15+
Database	MongoDB 6.0 or newer	MongoDB 7.0 (Local, Docker, or MongoDB Atlas)
Media Storage	S3-compatible object storage	AWS S3, Cloudflare R2, MinIO, or DigitalOcean Spaces
Git Provider	GitHub or GitLab account	GitHub App (repo access) + OAuth Apps (user login)
Reverse Proxy	Optional in dev, required in prod	Nginx or Caddy with WebSocket upgrade support

High-Level Architecture

The core Sitepins platform consists of two primary services:


┌──────────────────────────────────────────────────────────┐
│              Next.js 16 Web App (:3000)                  │
│       CMS Interface • Monaco Code Editor • Plate         │
└────────────┬─────────────────────────────┬───────────────┘
             │ HTTP / Cookies              │ Octokit / REST
             ▼                             ▼
┌───────────────────────────┐     ┌────────────────────────┐
│  Express 5 API (:4000)    │     │ GitHub / GitLab API    │
│  Auth • MongoDB • WS / IO │     │ (Site Content in Git)  │
└──────┬─────────────┬──────┘     └────────────────────────┘
       │ Mongoose    │ S3 API
       ▼             ▼
┌──────────────┐ ┌──────────────┐
│   MongoDB    │ │  S3 Bucket   │
│ (State/Auth) │ │ (App Assets) │
└──────────────┘ └──────────────┘

app/ (Next.js 16 App Router): Serves the browser interface, Plate rich-text visual editor, Monaco code editor, and communicates directly with Git providers (GitHub/GitLab) for content reads and commits.
api/ (Express 5): Handles user sessions via Better Auth, organization/project management, Socket.IO presence gateways, and the Hocuspocus WebSocket collaboration server.

Git provider credentials (such as your GitHub App private key) belong exclusively to the web app, not the API backend. The API never holds your repository signing keys.

Where Your Data Lives

Data Type	Destination	Durability & Ownership
Website Content & Media	Your Git repository	Single source of truth. Your content remains completely portable and versioned in Git.
Accounts & Organizations	MongoDB database	Stores user accounts, organization memberships, permissions, project configurations, and activity logs.
Application UI Assets	S3-compatible bucket	Stores user profile pictures (avatars), organization thumbnails, and project cover images.
AI API Keys	User’s browser (`localStorage`)	By default, AI keys are stored locally in the client browser (BYOK) and never saved to the database.

Licensing

Sitepins is released under the GNU Affero General Public License v3.0 (AGPLv3). You are free to run, inspect, fork, and modify the source code.

Network Use Under AGPLv3: If you modify Sitepins and make that modified version accessible to users over a network (including private SaaS or hosting for clients), you must make the corresponding modified source code available to those network users under the AGPLv3. Running the standard, unmodified open-source build incurs no such obligation.

Documentation Roadmap

Follow these dedicated guides to set up, deploy, and maintain your instance:

Architecture & Stack — In-depth breakdown of runtime processes, data flows, and security models.
Installation Guide — Step-by-step setup using Docker Compose or manual pnpm.
Environment Variables — Comprehensive reference for all api/.env and app/.env settings.
GitHub & GitLab Apps — How to configure OAuth and GitHub App credentials.
Media Storage — S3, Cloudflare R2, MinIO, and DigitalOcean Spaces configuration.
Reverse Proxy & SSL — Production Nginx and Caddy virtual host configurations with WebSockets.
Real-Time Collaboration & Preview — Architecture of Hocuspocus CRDTs and Vercel Sandboxes.
Project Configuration — .sitepins/config.json specification and sidebar arrangement.
API Reference — Complete REST and route handler endpoint documentation.
Extension Points & Hooks — Extending Sitepins without modifying core source code.
Troubleshooting & Runbook — Common error resolution and MongoDB disaster recovery.
Contributing to Core — Development workflows, Vitest testing, and quality guidelines.