Installation Guide

You can run Sitepins using two primary deployment methods:

1. Docker Compose (Recommended for self-hosters): Spins up MongoDB 7, the Express API, and the Next.js web application with a single command.
2. Manual pnpm setup: Ideal for local development, bare-metal servers, or custom orchestrators.

Method 1: Docker Compose

Sitepins includes a production-ready docker-compose.yml file in the root of the repository.

1. Clone the repository

git clone https://github.com/sitepins/sitepins.git
cd sitepins

2. Prepare environment files

Copy the template environment configuration files:

cp api/.env.example api/.env
cp app/.env.example app/.env

Generate your secrets (see Generating Secrets below) and populate your .env files.

3. Launch the stack

docker compose up --build -d

This starts three orchestrated containers:

• mongo: MongoDB 7 with persistent volume storage (mongo-data) and a configured mongosh ping healthcheck.
• api: The Express backend listening on http://localhost:4000. Starts automatically once MongoDB reports healthy.
• web: The Next.js web application listening on http://localhost:3000.

To view container logs in real time:

docker compose logs -f

To stop the stack:

docker compose down

Method 2: Manual Setup with pnpm

Prerequisites

Ensure your host environment has:

• Node.js: v22.0.0 or newer (node -v)
• pnpm: v11.0.0 or newer (pnpm -v)
• MongoDB: A running MongoDB instance locally or on MongoDB Atlas (mongodb://localhost:27017/sitepins).

1. Clone and Install Dependencies

git clone https://github.com/sitepins/sitepins.git
cd sitepins
pnpm install

2. Configure Environment Files

cp api/.env.example api/.env
cp app/.env.example app/.env

Edit api/.env and app/.env using the generated secrets and provider credentials described below.

3. Start in Development Mode

Run both the app and the API concurrently:

pnpm dev

Or run them in separate terminals:

# Terminal 1: Express API (Port 4000)
pnpm dev:api
 
# Terminal 2: Next.js Web App (Port 3000)
pnpm dev:app

4. Build and Run in Production

To build optimized production bundles:

# 1. Build backend TypeScript into api/dist
pnpm build:api
 
# 2. Build Next.js frontend into app/.next
pnpm build:app

Start the production servers:

# Start API
cd api && node dist/server.js
 
# Start Web App
cd app && pnpm start

Generating Secrets

Several required environment variables are high-entropy cryptographic keys. Generate them using standard terminal tools:

Better Auth Secret

Used to sign and verify user session cookies:

openssl rand -base64 32

Paste this value into BETTER_AUTH_SECRET in api/.env.

Token & Encryption Secrets

Generate three 64-character hexadecimal keys:

# 1. For JWT_SECRET (internal action tokens)
openssl rand -hex 32
 
# 2. For SANDBOX_ENCRYPTION_KEY (AES-256-GCM sandbox token encryption)
openssl rand -hex 32
 
# 3. For INTERNAL_API_SECRET (server-to-server authentication)
openssl rand -hex 32

Essential Configuration Checklist

Before booting your instance, ensure the following core variables are configured:

api/.env

• BASE_URL: Public API URL (e.g. http://localhost:4000 or https://api.example.com).
• MONGO_URI: MongoDB connection string (mongodb://localhost:27017/sitepins).
• BETTER_AUTH_SECRET: The base64 secret generated above.
• JWT_SECRET: The hex token secret generated above.
• SANDBOX_ENCRYPTION_KEY: The hex encryption key generated above.
• INTERNAL_API_SECRET: Shared secret with app/.env.
• S3_*: Object storage bucket credentials (see Media Storage).
• GITHUB_CLIENT_ID & GITHUB_CLIENT_SECRET: GitHub OAuth app for user login (see Git Apps).

app/.env

• NEXT_PUBLIC_BACKEND_URL: The API URL (http://localhost:4000 or https://api.example.com).
• NEXT_PUBLIC_HP_WS_URL: WebSocket URL (ws://localhost:4000/api/v1/editor/collab in dev, wss://api.example.com/api/v1/editor/collab in prod).
• NEXT_PUBLIC_BUCKET_URL: Public base URL of your S3 bucket.
• INTERNAL_API_SECRET: Identical to api/.env.
• GITHUB_APP_*: GitHub App credentials for repository reading and writing (see Git Apps).

For the full catalog of optional variables (branding, mail, AI, CORS, and proxy settings), see Environment Variables.

Health Check Verification

Test whether the backend API is alive and reachable:

curl http://localhost:4000/healthz

Expected response:

{
  "status": "ok",
  "uptime": 42.15
}

You can point Docker, Kubernetes, or load balancer liveness probes directly to /healthz.

Zero-Config Email & First Sign-up

Sitepins includes a provider-agnostic mail system:

1. Console Mailer (Default): When no SMTP server is configured, all verification codes, OTPs, and password reset links are printed directly to the API terminal stdout.
   • This means sign-up works immediately without setting up an email service.
   • When registering your first account at http://localhost:3000/sign-up, check your API terminal logs to find your 6-digit OTP verification code.
2. SMTP Relay: When ready for production email delivery, configure SMTP_HOST, SMTP_PORT, SMTP_USER, and SMTP_PASS in api/.env.
3. Bypass Verification: To disable email verification altogether for local development or closed intranets, set REQUIRE_EMAIL_VERIFICATION=false in api/.env.

Next Steps

• Configure your Environment Variables
• Set up your GitHub & GitLab Apps
• Connect Media Storage
• Configure Reverse Proxy & SSL