Docker Setup

Run Ballast on your infrastructure using Docker.

Enterprise customers can run Ballast on their own infrastructure using Docker Compose or Kubernetes.

Architecture

Ballast is a single binary that includes:

  • REST API server
  • Embedded SvelteKit frontend
  • WebSocket server for real-time features
  • MCP server endpoints
  • Background workflow worker

External dependencies:

ServicePurpose
PostgreSQL 16+Primary data store
QdrantVector database for embeddings
RedisCaching
TemporalBackground job orchestration

Quick Start with Docker Compose

Prerequisites

  • Docker and Docker Compose
  • 8 GB RAM minimum
  • OpenAI API key (for embeddings)

1. Get the Configuration

Contact us for access to the self-hosting package, or use the compose configuration:

services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_DB: ballast
      POSTGRES_USER: ballast
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data

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

  temporal:
    image: temporalio/auto-setup:1.24.2
    environment:
      - DB=postgres12
      - POSTGRES_SEEDS=postgres
    depends_on:
      - postgres

  ballast:
    image: ballast/ballast:latest
    env_file: .env
    ports:
      - "8080:8080"
    depends_on:
      - postgres
      - redis
      - qdrant
      - temporal

volumes:
  postgres_data:
  redis_data:
  qdrant_data:

2. Configure Environment

Create .env with required variables:

# Required
JWT_SECRET=your-secure-random-string
ENCRYPTION_KEY=base64-encoded-32-byte-key
OPENAI_API_KEY=sk-...

# Database
POSTGRES_HOST=postgres
POSTGRES_PORT=5432
POSTGRES_DB=ballast
POSTGRES_USER=ballast
POSTGRES_PASSWORD=secure-password

# Services
REDIS_HOST=redis
QDRANT_HOST=qdrant
TEMPORAL_HOST=temporal

3. Start Services

docker compose up -d

4. Verify

Check health:

curl http://localhost:8080/api/v1/health

Access the UI at http://localhost:8080

System Requirements

Minimum (Evaluation)

  • 4 vCPUs
  • 8 GB RAM
  • 50 GB storage

Recommended (Production)

  • 8+ vCPUs
  • 32 GB RAM
  • 500 GB SSD
  • Separate database instances

Kubernetes Deployment

For Kubernetes deployments, Helm charts are available. Contact us for access.

helm repo add ballast https://charts.ballast.sh
helm install ballast ballast/ballast -f values.yaml

Network Requirements

Outbound

Ballast needs outbound access to:

  • Data source APIs (Google, Microsoft, Slack, etc.)
  • OpenAI API (for embeddings)
  • OAuth providers

Inbound

  • Port 8080 (or your configured port) for HTTP/HTTPS

Next Steps