Deployment Guide

Deployment Guide

Quick Reference

• Platform: npm (CLI), npm (SDK), Vercel (Web), Docker (Database)
• Min Requirements: Bun ≥1.3.5, Node.js ≥18 (SDK consumers), PostgreSQL
• Ports: 3000 (web), 4242 (API server), 5432 (PostgreSQL)
• Health Check: Web application via Vercel health endpoints

System Requirements

Component	Minimum	Recommended
CPU	2 cores	4+ cores
RAM	4 GB	8+ GB
Disk	2 GB	10+ GB (for large projects)
Bun	1.3.5	Latest
Node.js	18.0 (SDK only)	20+
PostgreSQL	14	16+

Environment Variables

Variable	Description	Required	Example
OPEN_ROUTER_API_KEY	OpenRouter API key for LLM access	✅	sk-or-v1-...
OPENAI_API_KEY	OpenAI API key (optional, for direct access)	❌	sk-...
ANTHROPIC_API_KEY	Anthropic API key (optional)	❌	sk-ant-...
DATABASE_URL	PostgreSQL connection string	✅	postgresql://user:pass@localhost:5432/db
PORT	API server port	❌	4242
CODEBUFF_GITHUB_ID	GitHub OAuth App client ID	✅	Iv1.abc123
CODEBUFF_GITHUB_SECRET	GitHub OAuth App secret	✅	ghs_...
NEXTAUTH_SECRET	NextAuth session encryption (≥32 chars)	✅	random string
STRIPE_SECRET_KEY	Stripe secret key	✅	sk_test_...
STRIPE_WEBHOOK_SECRET_KEY	Stripe webhook verification	✅	whsec_...
NEXT_PUBLIC_CB_ENVIRONMENT	Environment name	❌	dev, production
NEXT_PUBLIC_CODEBUFF_APP_URL	Public app URL	✅	http://localhost:3000
NEXT_PUBLIC_POSTHOG_API_KEY	PostHog analytics key	❌	phc_...
DISCORD_BOT_TOKEN	Discord bot integration	❌	Bot token
LOOPS_API_KEY	Loops email automation	❌	API key

:::warning Security Never commit .env files. Use secrets management in production. Copy .env.example to .env for local development. :::

(.env.example)

Local Development Setup

# Step 1: Clone the repository
git clone https://github.com/CodebuffAI/codebuff.git
cd codebuff

# Step 2: Install Bun (if not already installed)
curl -fsSL https://bun.sh/install | bash

# Step 3: Install dependencies
bun install

# Step 4: Configure environment
cp .env.example .env
# Edit .env with your API keys and database URL

# Step 5: Start database
bun start-db

# Step 6: Run the CLI in development
bun dev

# Or start the web application
bun start-web

CLI Installation (End Users)

# Install globally
npm install -g codebuff

# Run in any project
cd your-project
codebuff

SDK Installation (Developers)

# Install the SDK package
npm install @codebuff/sdk

import { CodebuffClient } from '@codebuff/sdk'

const client = new CodebuffClient({
  apiKey: 'your-api-key',
  cwd: '/path/to/your/project',
})

const result = await client.run({
  agent: 'base',
  prompt: 'Add error handling to all API endpoints',
})

Docker Deployment (Database)

# docker-compose.yml (from packages/internal/src/db/)
version: '3.8'
services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: manicode_user_local
      POSTGRES_PASSWORD: secretpassword_local
      POSTGRES_DB: manicode_db_local
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

CI/CD Pipeline

graph LR
    A["🔀 Push"] --> B["🧪 Typecheck"]
    B --> C["🧪 Test"]
    C --> D["📦 Build"]
    D --> E{"Branch?"}
    E -->|main| F["🚀 Deploy"]
    E -->|PR| G["📝 Preview"]

Available Scripts:

Script	Command	Description
Dev CLI	bun dev	Start CLI in development mode
Dev Web	bun start-web	Start web app + database
Start DB	bun start-db	Launch PostgreSQL via Docker
DB Studio	bun start-studio	Open Drizzle Studio
Typecheck	bun typecheck	Run TypeScript type checking
Test	bun test	Run all workspace tests
Format	bun format	Prettier formatting
Release CLI	bun release:cli	Publish CLI to npm
Release SDK	bun release:sdk	Publish SDK to npm
Clean	bun clean-ts	Remove build artifacts

(package.json:18-36)

Database Migrations

# Run pending migrations
bun --cwd packages/internal drizzle-kit push

# Generate new migration
bun --cwd packages/internal drizzle-kit generate

# Open database studio
bun start-studio

Monitoring & Health

Endpoint	Purpose	Expected
Web app root	Application health	200 OK
/api/* routes	API functionality	200 OK / 401
PostgreSQL	Database connectivity	Connection success

Related Pages

• Architecture — System design
• Database — Schema documentation
• Data Flow — Data flow diagrams