Deployment

Self-Hosting

Capsul is fully open-source and designed to run on your own server. Two deployment modes are supported depending on your infrastructure.

Mode A — Single VPS (recommended)

Run both Next.js and Express on one server. Next.js builds to production and Express handles API calls and serves deployed apps.

# One-time setup
git clone https://github.com/your-org/capsul
cd capsul
cp .env.local.example .env.local   # fill in values
npm install
npm run build
pm2 start ecosystem.config.js

# Express server
cd server
cp .env.example .env   # fill in values
npm install
npm run build
pm2 start ecosystem.config.js

Mode B — Vercel + VPS

Deploy Next.js to Vercel and run Express on a VPS. Set NEXT_PUBLIC_API_URL to your VPS domain and SPLIT_MODE=true.

# Vercel: add all env vars in dashboard, then deploy
vercel deploy --prod

# VPS: just the Express server
cd server && npm run build && pm2 start index.js

Environment variables

Variable	Description	Example
NEXTAUTH_URL	Public URL of your Next.js site	https://capsul.example.com
NEXT_PUBLIC_FIREBASE_*	Firebase client config (7 vars)	from Firebase console
FIREBASE_ADMIN_*	Firebase Admin SDK credentials	service account JSON fields
ENCRYPTION_KEY	AES-256 key for API key encryption	64-char hex string
JWT_SECRET	HS256 secret for CapsulDB tokens	long random string
CAPSUL_DATA_DIR	Directory for SQLite app databases	/data/capsul
NEXT_PUBLIC_API_URL	Express server URL (split mode)	https://api.capsul.example.com
NEXT_PUBLIC_APPS_BASE_URL	Base URL for deployed app links	https://capsul.example.com
SUPER_ADMIN_EMAILS	Comma-separated admin email addresses	admin@example.com

See .env.local.example and server/.env.example in the repo.

Nginx reverse proxy

server {
  listen 443 ssl;
  server_name capsul.example.com;

  location / {
    proxy_pass http://localhost:3000;   # Next.js
  }

  location /api/ {
    proxy_pass http://localhost:4000;   # Express (split mode)
  }
}

See nginx/capsul.conf in the repo for the full template.

Data directory

App SQLite files are stored under CAPSUL_DATA_DIR. Back them up with:

tar -czf capsul-backup-$(date +%F).tar.gz /data/capsul

← Download Next: FAQ →