Self-Hosting

Installation Guide

Everything you need to run ContextStream on your own infrastructure — from a single Docker Compose command to a production Kubernetes cluster.

MIT LicensedDocker + HelmPostgreSQL + pgvector

Step 1

Quick Start — Docker Compose

The fastest way to get ContextStream running locally or on a single server.

Prerequisites: Docker 24+, Docker Compose v2, and a PostgreSQL 14+ database with the pgvector extension. You can use Neon or Supabase for a managed option, or the bundled Postgres container in the Compose file.

terminal — 5 steps

# 1. Clone the repo
git clone https://github.com/jimseiwert/context-stream
cd context-stream

# 2. Copy and configure environment
cp .env.example .env
# Edit .env: set DATABASE_URL, BETTER_AUTH_SECRET, OPENAI_API_KEY

# 3. Start with Docker Compose (migrations run automatically on startup)
docker compose -f docker/docker-compose.yml up -d

# 4. Open http://localhost:3000
# The first user to register automatically becomes SUPER_ADMIN

That's it. The application, worker, and Postgres container all start together. Once migrations are done, visit http://localhost:3000 and register your admin account.

Configuration

Environment Variables

Copy .env.example to .env and set the values below. Required variables must be present before starting the application.

VariableRequiredDescription

DATABASE_URLrequiredPostgreSQL connection string. Must have pgvector extension enabled.

BETTER_AUTH_SECRETrequiredRandom 32+ character secret. Generate one: openssl rand -base64 32

OPENAI_API_KEYembeddingsOpenAI API key for text-embedding-3-small (default embedding provider).

GITHUB_CLIENT_IDoptionalGitHub OAuth app client ID for GitHub social login.

GITHUB_CLIENT_SECREToptionalGitHub OAuth app client secret for GitHub social login.

GOOGLE_CLIENT_IDoptionalGoogle OAuth client ID for Google social login.

GOOGLE_CLIENT_SECREToptionalGoogle OAuth client secret for Google social login.

NEXT_PUBLIC_APP_URLoptionalPublic base URL of your deployment (e.g. https://docs.example.com). Used for OAuth callbacks and MCP config.

PDF_PARSER_URLoptionalURL of the PDF parser microservice (e.g. http://pdf-parser:8000). Enables PDF source indexing.

DISPATCH_MODEoptionalJob dispatch mode: INPROCESS (default), WORKER, or KUBERNETES.

NEXT_PUBLIC_SAAS_MODEoptionalSet to true to enable billing and subscription features.

STRIPE_SECRET_KEYsaas onlyStripe secret key. Required when NEXT_PUBLIC_SAAS_MODE=true.

LICENSE_KEYenterpriseEnterprise license key. Unlocks SSO, Confluence integration, and Notion integration.

Production Deploy

Kubernetes / Helm

Use the bundled Helm chart for production Kubernetes deployments with ingress and auto-scaling.

terminal — Helm install

# Install from the bundled chart (migrations run automatically as a pre-install Job)
helm install contextstream ./helm/contextstream \
  --set secrets.DATABASE_URL="postgresql://user:pass@host:5432/db" \
  --set secrets.BETTER_AUTH_SECRET="$(openssl rand -base64 32)" \
  --set secrets.OPENAI_API_KEY="sk-..." \
  --set env.NEXT_PUBLIC_APP_URL="https://contextstream.example.com" \
  --set ingress.enabled=true \
  --set ingress.hosts[0].host="contextstream.example.com" \
  --set migrations.strategy=job

Horizontal scaling

Scale the app deployment independently from the worker. The worker uses DISPATCH_MODE=KUBERNETES to spawn job pods on demand.

Ingress + TLS

Set ingress.enabled=true and provide a cert-manager annotation to get automatic HTTPS via Let's Encrypt.

Data Layer

Database Setup

ContextStream requires PostgreSQL 14+ with the pgvector extension for hybrid vector search.

Neon ↗

Serverless Postgres with pgvector. Free tier available. Recommended for cloud deployments.

Supabase ↗

Managed Postgres with pgvector pre-installed. Includes a generous free tier.

Self-hosted

Any Postgres 14+ instance. Run CREATE EXTENSION IF NOT EXISTS vector; before migrating.

psql — manual extension install (self-hosted)

-- Run once on your Postgres instance before migrating
CREATE EXTENSION IF NOT EXISTS vector;

terminal — migrations and seed

# Run all pending migrations
npm run db:migrate

# Seed the database (creates admin user + sample source)
npm run db:seed

The migration runner automatically installs the vector extension if it is not present. If your database user lacks superuser privileges, install the extension manually first using the command above.

AI Configuration

Embedding Providers

ContextStream supports three embedding backends. The first admin configures the provider via Admin → System → Embedding Config.

OpenAIdefault

Set OPENAI_API_KEY. Uses text-embedding-3-small. Best choice for most deployments.

Azure OpenAIsupported

Configure endpoint, key, and deployment name in Admin → System → Embedding Config.

Vertex AIsupported

Configure project ID and region in Admin → System → Embedding Config.

The default provider is OpenAI. To switch providers, log in as a super admin and navigate to Admin → System → Embedding Config. All three providers generate 1536-dimensional embeddings that are stored in the pgvector column alongside BM25 keyword indexes for hybrid search.

Job Processing

Worker Dispatch Modes

Choose how scraping and embedding jobs are dispatched. Set via the DISPATCH_MODE environment variable.

ModeConfig valueUse case

INPROCESSdefault

DISPATCH_MODE=INPROCESSJobs run inside the Next.js process. Best for single-server installs and local development.

External Worker

DISPATCH_MODE=WORKERA separate worker container picks up jobs from the queue. Better isolation and resource control.

Kubernetesenterprise

DISPATCH_MODE=KUBERNETESEach job spawns a short-lived Kubernetes pod. Enables auto-scaling and zero idle worker cost.

To run an external worker alongside the app container:

terminal — external worker profile

docker compose -f docker/docker-compose.yml --profile worker up -d

AI Tool Integration

MCP Server Setup

The MCP server runs at /api/mcp on your deployment. Connect it to Claude Desktop, Cursor, Zed, or any MCP-compatible tool.

Generate your API key in the app under Settings → API Keys, then add the config block below to your AI tool. Replace your-domain.com and YOUR_API_KEY.

claude_desktop_config.json

{
  "mcpServers": {
    "contextstream": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-http-client"],
      "env": {
        "MCP_SERVER_URL": "https://your-domain.com/api/mcp",
        "MCP_AUTH_HEADER": "Authorization: Bearer YOUR_API_KEY"
      }
    }
  }
}

Tip: After logging in, visit /mcp in the app for pre-generated config snippets tailored to Claude Desktop, Cursor, Zed, and Windsurf.

Maintenance

Upgrading

Always run database migrations after pulling a new image or chart version.

Docker Compose

terminal

# Pull latest images
docker compose -f docker/docker-compose.yml pull

# Restart containers (migrations run automatically on startup)
docker compose -f docker/docker-compose.yml up -d

Helm / Kubernetes

terminal

# Upgrade the Helm release (migrations run automatically as a pre-upgrade Job)
helm upgrade contextstream ./helm/contextstream --reuse-values

Before upgrading: Review the release notes for breaking changes. Back up your database before running migrations in production.

Need help?

Open a GitHub issue for bug reports, feature requests, or questions about self-hosting. Community support is available on the repository discussions tab.

Open an Issue View on GitHub

# 1. Clone the repo git clone https://github.com/jimseiwert/context-stream cd context-stream # 2. Copy and configure environment cp .env.example .env # Edit .env: set DATABASE_URL, BETTER_AUTH_SECRET, OPENAI_API_KEY # 3. Start with Docker Compose (migrations run automatically on startup) docker compose -f docker/docker-compose.yml up -d # 4. Open http://localhost:3000 # The first user to register automatically becomes SUPER_ADMIN

# Install from the bundled chart (migrations run automatically as a pre-install Job) helm install contextstream ./helm/contextstream \ --set secrets.DATABASE_URL="postgresql://user:pass@host:5432/db" \ --set secrets.BETTER_AUTH_SECRET="$(openssl rand -base64 32)" \ --set secrets.OPENAI_API_KEY="sk-..." \ --set env.NEXT_PUBLIC_APP_URL="https://contextstream.example.com" \ --set ingress.enabled=true \ --set ingress.hosts[0].host="contextstream.example.com" \ --set migrations.strategy=job

{ "mcpServers": { "contextstream": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-http-client"], "env": { "MCP_SERVER_URL": "https://your-domain.com/api/mcp", "MCP_AUTH_HEADER": "Authorization: Bearer YOUR_API_KEY" } } } }