Skip to main content

Self-Hosting

Self-Hosting​

OpenCap Stack is MIT licensed. Run it on your own servers, in your own cloud, with your own data. No vendor lock-in.

GitHub: github.com/Open-Cap-Stack/opencapstack

Option A — Docker (Recommended)​

## 1. Clone the repo
git clone https://github.com/Open-Cap-Stack/opencapstack.git
cd opencapstack

## 2. Copy and configure environment
cp .env.example .env
## Edit .env with your values (see Environment Variables below)

## 3. Start with Docker Compose
docker compose up -d

## Backend API:  http://localhost:3000/api/v1
## Swagger UI:   http://localhost:3000/api-docs
## Frontend:     http://localhost:5173

Option B — Node.js​

## 1. Clone and install
git clone https://github.com/Open-Cap-Stack/opencapstack.git
cd opencapstack
npm install

## 2. Configure environment
cp .env.example .env

## 3. Start backend
npm run dev          # nodemon, hot reload
## or
npm start            # production

## 4. Start frontend (separate terminal)
cd client
npm install
npm run dev          # Next.js on port 5173

Environment Variables​

Required​

## Primary Database — ZeroDB (AINative)
ENABLE_ZERODB=true
ZERODB_API_KEY=your-zerodb-api-key
ZERODB_BASE_URL=https://api.ainative.studio/api/v1
AINATIVE_API_TOKEN=your-ainative-token

## Server
PORT=3000
JWT_SECRET=your-256-bit-random-secret
NODE_ENV=production

Optional​

## AINative SSO (enables /auth/ainative-login endpoint)
AINATIVE_API_URL=https://api.ainative.studio

## Document storage (MinIO / S3-compatible)
MINIO_ENDPOINT=your-minio-host
MINIO_PORT=9000
MINIO_ACCESS_KEY=your-access-key
MINIO_SECRET_KEY=your-secret-key
MINIO_BUCKET=opencapstack-docs

## Frontend URL (for CORS)
NEXT_PUBLIC_API_URL=http://localhost:3000/api/v1
NEXT_PUBLIC_SITE_URL=http://localhost:5173

## Admin token generation (for server-side use only)
ADMIN_SECRET=your-admin-secret

## OAuth providers
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...

ZeroDB Setup​

OpenCap Stack uses ZeroDB as its primary database. Get your credentials at ainative.studio:

  1. Create an AINative account
  2. Go to ZeroDB → New Project
  3. Copy the API Key and Project ID
  4. Set ZERODB_API_KEY and AINATIVE_API_TOKEN in your .env

ZeroDB provides vectors, tables, file storage, and graph capabilities — no additional database required.

Production Deployment​

Railway​

## Install Railway CLI
npm install -g @railway/cli

## Login and link project
railway login
railway link

## Deploy
railway up

Set environment variables in the Railway dashboard under Variables.

Fly.io​

fly launch --name my-opencapstack
fly secrets set JWT_SECRET=... ZERODB_API_KEY=... AINATIVE_API_TOKEN=...
fly deploy

Self-Managed VPS (nginx + PM2)​

## Install PM2
npm install -g pm2

## Start the backend
pm2 start npm --name "opencap-api" -- start
pm2 save

## Build and serve frontend
cd client
npm run build
pm2 start npm --name "opencap-frontend" -- start

nginx config:

server {
    listen 443 ssl;
    server_name api.yourcompany.com;

    location /api/ {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

server {
    listen 443 ssl;
    server_name yourcompany.com;

    location / {
        proxy_pass http://localhost:5173;
        proxy_set_header Host $host;
    }
}

Pointing the MCP Server at Your Instance​

{
  "mcpServers": {
    "opencap": {
      "command": "npx",
      "args": ["-y", "@opencapstack/mcp-server"],
      "env": {
        "OPENCAP_API_KEY": "your-api-key",
        "OPENCAP_BASE_URL": "https://api.yourcompany.com/api/v1"
      }
    }
  }
}

Health Check​

curl https://your-host/api/v1/health
{
  "status": "ok",
  "version": "1.0.0",
  "database": "connected",
  "storage": "connected",
  "uptime": 3600
}

License​

MIT — use it, modify it, deploy it commercially. No royalties, no seat fees.

Copyright (c) 2024 Open-Cap-Stack

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software...

Full license: github.com/Open-Cap-Stack/opencapstack/blob/main/LICENSE