Installation Guide
You can run Sitepins using two primary deployment methods:
- Docker Compose (Recommended for self-hosters): Spins up MongoDB 7, the Express API, and the Next.js web application with a single command.
- Manual pnpm setup: Ideal for local development, bare-metal servers, or custom orchestrators.
Method 1: Docker Compose
Install Docker Engine or Docker Desktop with Docker Compose v2.24 or later, and have openssl available on your host. On Windows, run the setup command in Git Bash or WSL.
1. Clone and configure
git clone https://github.com/sitepins/sitepins.git
cd sitepins
sh scripts/setup-docker.shThe script creates private api/.env and app/.env files and preserves existing files. It puts all four generated secrets in api/.env. If you already have that file, supply any missing secrets using the formats below. The Docker script loads both files explicitly.
2. Build and start
sh scripts/docker.sh up --build --waitThe first build downloads dependencies and compiles the app. Compose waits for MongoDB to become a replica set primary, then starts the API and web app.
| Service | Where to reach it |
|---|---|
| Web | http://localhost:3000/registerΒ |
| API | http://localhost:4000/healthzΒ |
| MongoDB | Inside Compose only; data lives in the mongo-data volume |
Use localhost in your browser. If a port is already in use, set WEB_PORT in app/.env or API_PORT in api/.env and rerun the build command. For a public instance, configure HTTPS and a reverse proxy.
3. Create an account and configure integrations
Register in the web app and find the email verification code with sh scripts/docker.sh logs api. Configure SMTP in api/.env when other people need to receive codes, invites, or password reset links. Follow the Git apps guide to connect a repository and the media storage guide to enable uploads.
Set browser-facing NEXT_PUBLIC_* variables in app/.env and run sh scripts/docker.sh up --build --wait after changing them. Use api/.env for optional runtime settings such as mail and S3 credentials, and app/.env for runtime settings such as the GitHub App private key.
sh scripts/docker.sh ps
sh scripts/docker.sh logs --tail=100 mongo api web
sh scripts/docker.sh downsh scripts/docker.sh down keeps the database. The -v flag deletes the volume and its data. Back up the database and api/.env together.
Set your brand
The default Docker build uses the name βCMSβ, a neutral icon, and no vendor links. Use app/.env.example as a reference to set your own name, logo, favicon, and optional links. Set NEXT_PUBLIC_BRAND_SLUG before creating projects: it names the repository configuration folder and determines cookie and upload prefixes. Use NEXT_PUBLIC_SOURCE_URL for your own source URL.
Upgrading an existing Compose install
If you previously used a root .env, move its values before rebuilding. Merge them into your existing service files.
- In
api/.env, preserveBETTER_AUTH_SECRET,JWT_SECRET,INTERNAL_API_SECRET, andSANDBOX_ENCRYPTION_KEY. Also move API settings such asMONGO_URI,BASE_URL,APP_URL,CORS_ORIGINS,TRUST_PROXY,API_PORT, andJWT_TOKEN_EXPIRE. - In
app/.env, move allNEXT_PUBLIC_*settings andWEB_PORT. SetNEXT_PUBLIC_BRAND_SLUGto the current slug so repository settings and media still resolve.
If the root file set COMPOSE_PROJECT_NAME, move it to api/.env so Compose reuses the same database volume. Run the setup script to create any missing service file, then start the stack with sh scripts/docker.sh up --build --wait.
Method 2: Manual Setup with pnpm
Prerequisites
Ensure your host environment has:
- Node.js:
v22.0.0or newer (node -v) - pnpm: The version pinned in
package.json - MongoDB: A running replica set locally or on MongoDB Atlas.
1. Clone and Install Dependencies
git clone https://github.com/sitepins/sitepins.git
cd sitepins
pnpm install2. Configure Environment Files
cp api/.env.example api/.env
cp app/.env.example app/.envEdit 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 devOr run them in separate terminals:
# Terminal 1: Express API (Port 4000)
pnpm dev:api
# Terminal 2: Next.js Web App (Port 3000)
pnpm dev:app4. 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:appStart the production servers:
# Start API
cd api && node dist/server.js
# Start Web App
cd app && pnpm startGenerating Secrets for Manual Setup
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 32Paste 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 32Crucial Configuration Rule:
INTERNAL_API_SECRET must be byte-for-byte identical in both api/.env and app/.env. If these keys do not match, frontend requests to internal API preview and validation routes will fail with 401 Unauthorized.
Essential Configuration for Manual Setup
Before booting your instance, ensure the following core variables are configured:
api/.env
BASE_URL: Public API URL (e.g.http://localhost:4000orhttps://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 withapp/.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/api/v1orhttps://api.example.com/api/v1).NEXT_PUBLIC_HP_WS_URL: WebSocket URL (ws://localhost:4000/api/v1/editor/collabin dev,wss://api.example.com/api/v1/editor/collabin prod).NEXT_PUBLIC_BUCKET_URL: Public base URL of your S3 bucket.INTERNAL_API_SECRET: Identical toapi/.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/healthzExpected 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:
- Console Mailer (Default): When no SMTP server is configured, all verification codes, OTPs, and password reset links are printed in the API logs.
- This means sign-up works immediately without setting up an email service.
- When registering your first account at
http://localhost:3000/register, check your API terminal logs to find your 6-digit OTP verification code.
- SMTP Relay: When ready for production email delivery, configure
SMTP_HOST,SMTP_PORT,SMTP_USER, andSMTP_PASSinapi/.env. - Bypass Verification: To disable email verification altogether for local development or closed intranets, set
REQUIRE_EMAIL_VERIFICATION=falseinapi/.env.
Next Steps
- Configure your Environment Variables
- Set up your GitHub & GitLab Apps
- Connect Media Storage
- Configure Reverse Proxy & SSL