Deployment

Self-Hosting

Deploy Octopus on your own infrastructure. Your code never leaves your servers.

Prerequisites

PostgreSQL 15+

Primary database for all application data.

Qdrant

Vector database for code embeddings and search.

Node.js 20+ or Bun

Runtime for the Next.js application.

OpenAI API Key

For generating code embeddings (text-embedding-3-large).

You'll also need an AI provider key (Anthropic Claude or OpenAI) for the review engine.

Quick Start with Docker

Clone the repository

git clone https://github.com/octopusreview/octopus.git
cd octopus

Create your .env file

Use the environment generator below to create a .env file with a pre-generated auth secret, then save it to the project root. Fill in your API keys before continuing.

Start with Docker Compose

The project includes a docker-compose.yml that runs Octopus, PostgreSQL, and Qdrant together. Database and Qdrant URLs are automatically configured for Docker's internal network.

docker-compose.yml

services:
  octopus:
    build:
      context: .
      dockerfile: apps/web/Dockerfile
    ports:
      - "3000:3000"
    env_file:
      - .env
    environment:
      DATABASE_URL: postgresql://octopus:octopus@postgres:5432/octopus
      QDRANT_URL: http://qdrant:6333
    depends_on:
      postgres:
        condition: service_healthy
      qdrant:
        condition: service_started
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: octopus
      POSTGRES_USER: octopus
      POSTGRES_PASSWORD: octopus
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U octopus"]
      interval: 5s
      timeout: 5s
      retries: 5

  qdrant:
    image: qdrant/qdrant:latest
    volumes:
      - qdrant_data:/qdrant/storage

volumes:
  pgdata:
  qdrant_data:

Build and run

docker compose up -d --build

First run will build the Octopus image from source — this may take a few minutes. Subsequent starts use the cached image.

Run database migrations

docker compose exec octopus bun run db:migrate

Open Octopus

Visit http://localhost:3000 to access your self-hosted Octopus instance. Create your first account and connect a GitHub repository to get started.

Environment Variables

Generate a default .env file with pre-filled defaults for database, Qdrant, and auth. A unique BETTER_AUTH_SECRET is generated automatically. Fill in the remaining values (API keys, GitHub App, etc.) before starting.

.env

# Database (overridden by docker-compose when using Docker)
DATABASE_URL=postgresql://octopus:octopus@localhost:5432/octopus

# Qdrant (overridden by docker-compose when using Docker)
QDRANT_URL=http://localhost:6333
QDRANT_API_KEY=

# Auth
BETTER_AUTH_SECRET=853df48d3c1b6786db3300c22a5c0a9972b9082150ac70aadc606411f2ea15e3
BETTER_AUTH_URL=http://localhost:3000

# AI Providers
OPENAI_API_KEY=
ANTHROPIC_API_KEY=

# GitHub App
GITHUB_APP_ID=
GITHUB_APP_PRIVATE_KEY=
GITHUB_WEBHOOK_SECRET=
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
NEXT_PUBLIC_GITHUB_APP_SLUG=

# Optional
COHERE_API_KEY=
STRIPE_SECRET_KEY=
STRIPE_WEBHOOK_SECRET=
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=

Required — fill these in

OPENAI_API_KEYrequired

Used for embeddings

ANTHROPIC_API_KEY

Claude for reviews

GITHUB_APP_IDrequired

123456

GITHUB_APP_PRIVATE_KEYrequired

-----BEGIN RSA...

GITHUB_WEBHOOK_SECRETrequired

whsec_...

GITHUB_CLIENT_ID

Iv1.abc123

GITHUB_CLIENT_SECRET

secret

Pre-filled defaults

DATABASE_URLrequired

postgresql://octopus:octopus@localhost:5432/octopus

QDRANT_URLrequired

http://localhost:6333

BETTER_AUTH_SECRETrequired

Auto-generated (64-char hex)

BETTER_AUTH_URLrequired

http://localhost:3000

Optional

QDRANT_API_KEY

If Qdrant auth is enabled

COHERE_API_KEY

For reranking search results

STRIPE_SECRET_KEY

For billing

Database Setup

Run migrations to set up the database schema:

# If running from source
bun run db:migrate

# If running with Docker
docker exec -it octopus-web bun run db:migrate

GitHub App Setup

To receive webhook events, you need to create a GitHub App:

Go to GitHub Settings → Developer settings → GitHub Apps
Create a new GitHub App with a webhook URL pointing to https://your-domain/api/github/webhook
Enable permissions: Pull requests (read/write), Contents (read), Checks (read/write)
Subscribe to events: Pull request, Pull request review
Generate a private key and add it to your environment

Production Tips

Use connection pooling

Use PgBouncer or Supabase pooler for PostgreSQL connections. Next.js serverless functions can exhaust connection limits quickly.

Secure Qdrant

Enable API key authentication on Qdrant and restrict network access. Never expose Qdrant directly to the internet.

Set a spend limit

Configure per-organization spend limits in the admin panel to control AI costs.

Enable HTTPS

Use a reverse proxy (nginx, Caddy, Traefik) with TLS termination. Required for OAuth callbacks.

Running without Docker

If you prefer to run Octopus directly, you'll need PostgreSQL, Qdrant, and Bun installed on your machine. Create your .env file first using the generator above.

git clone https://github.com/octopusreview/octopus.git
cd octopus
bun install
bun run db:generate
bun run db:migrate
bun run build
bun run start

The standalone output is at apps/web/.next/standalone. You can deploy this directory directly.