Self-Hosting — bRRAIn Docs

Deploy bRRAIn on your own infrastructure with Docker, Kubernetes, or bare metal. Configuration and operational guidance.

Self-Hosting

bRRAIn can be deployed on your own infrastructure for organizations that require full control over data residency, network boundaries, or compliance scope. This guide covers system requirements, deployment options, and operational configuration.

System Requirements

Minimum (Development/Testing)

| Component | Specification | |-----------|--------------| | CPU | 4 cores (x86_64 or arm64) | | RAM | 8 GB | | Disk | 50 GB SSD | | OS | Ubuntu 22.04 LTS, Debian 12, RHEL 9, or Amazon Linux 2023 | | Docker | 24.0+ with Compose 2.20+ | | PostgreSQL | 15+ | | Redis | 7+ |

| Component | Specification | |-----------|--------------| | CPU | 16+ cores | | RAM | 64+ GB | | Disk | 500+ GB NVMe SSD (RAID-10 recommended) | | Network | 1 Gbps minimum, 10 Gbps recommended | | PostgreSQL | 16 with streaming replication | | Redis | 7+ in Sentinel or Cluster mode | | Load Balancer | NGINX, HAProxy, or cloud ALB |

For GPU-accelerated embedding generation, add one or more NVIDIA GPUs with at least 8 GB VRAM (T4, A10, or A100). CPU-based embedding generation is available but slower.

Docker Deployment

The simplest self-hosted deployment uses Docker Compose.

Step 1: Create the Configuration

mkdir brrain-self-hosted && cd brrain-self-hosted

cat > .env <<EOF
BRRAIN_PORT=8080
BRRAIN_DB_URL=postgres://brrain:changeme@db:5432/brrain?sslmode=disable
BRRAIN_REDIS_URL=redis://redis:6379/0
BRRAIN_ENCRYPTION_KEY=$(openssl rand -base64 32)
BRRAIN_LICENSE_KEY=your-license-key-here
BRRAIN_LOG_LEVEL=info
BRRAIN_DOMAIN=brrain.yourcompany.com
BRRAIN_CORS_ORIGINS=https://brrain.yourcompany.com
EOF

Step 2: Create the Compose File

version: "3.9"
services:
  brrain:
    image: ghcr.io/qosil/brrain:latest
    ports:
      - "8080:8080"
    env_file: .env
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/healthz"]
      interval: 30s
      timeout: 5s
      retries: 3

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

  redis:
    image: redis:7-alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

volumes:
  pgdata:

Step 3: Start and Migrate

docker compose up -d
docker compose exec brrain /brrain migrate up
curl http://localhost:8080/healthz

Kubernetes Deployment

For production environments, deploy bRRAIn on Kubernetes using our Helm chart.

Install the Helm Chart

helm repo add brrain https://charts.brrain.io
helm repo update

helm install brrain brrain/brrain \
  --namespace brrain \
  --create-namespace \
  --set config.licenseKey="your-license-key" \
  --set config.encryptionKey="$(openssl rand -base64 32)" \
  --set postgresql.enabled=true \
  --set redis.enabled=true \
  --set ingress.enabled=true \
  --set ingress.hosts[0].host=brrain.yourcompany.com

Helm Values Reference

Key configuration values:

replicaCount: 3
image:
  repository: ghcr.io/qosil/brrain
  tag: latest

config:
  licenseKey: ""
  encryptionKey: ""
  logLevel: info
  domain: brrain.yourcompany.com

postgresql:
  enabled: true
  auth:
    postgresPassword: changeme
    database: brrain
  primary:
    persistence:
      size: 100Gi

redis:
  enabled: true
  architecture: replication

ingress:
  enabled: true
  className: nginx
  tls:
    - secretName: brrain-tls
      hosts:
        - brrain.yourcompany.com

resources:
  requests:
    cpu: 2000m
    memory: 4Gi
  limits:
    cpu: 8000m
    memory: 16Gi

autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 20
  targetCPUUtilizationPercentage: 70

Production Considerations

  • TLS termination: Configure TLS at the ingress controller or load balancer level
  • Database: Use a managed PostgreSQL service (RDS, Cloud SQL, Azure Database) for production reliability
  • Redis: Use a managed Redis service or deploy Redis Sentinel for high availability
  • Storage class: Use fast SSD-backed storage classes for database volumes
  • Pod disruption budgets: Set minAvailable: 2 to ensure availability during rolling updates

Configuration Reference

All configuration is done through environment variables:

| Variable | Description | Default | |----------|-------------|---------| | BRRAIN_PORT | HTTP listen port | 8080 | | BRRAIN_DB_URL | PostgreSQL connection string | Required | | BRRAIN_REDIS_URL | Redis connection string | Required | | BRRAIN_ENCRYPTION_KEY | Base64-encoded 256-bit encryption key | Required | | BRRAIN_LICENSE_KEY | Self-hosted license key | Required | | BRRAIN_DOMAIN | Primary domain for the deployment | localhost | | BRRAIN_LOG_LEVEL | Logging level | info | | BRRAIN_CORS_ORIGINS | Allowed CORS origins | * | | BRRAIN_MAX_MEMORY_SIZE | Max size per memory object (bytes) | 1048576 | | BRRAIN_EMBEDDING_DEVICE | Device for embeddings: cpu or cuda | cpu | | BRRAIN_BACKUP_S3_BUCKET | S3 bucket for automated backups | Optional | | BRRAIN_BACKUP_SCHEDULE | Cron expression for backup schedule | 0 2 * * * | | BRRAIN_METRICS_ENABLED | Enable Prometheus metrics endpoint | true | | BRRAIN_TRACING_ENDPOINT | OpenTelemetry collector endpoint | Optional |

Backup and Recovery

Automated Backups

Configure automated backups by setting the S3 bucket and schedule:

BRRAIN_BACKUP_S3_BUCKET=my-brrain-backups
BRRAIN_BACKUP_SCHEDULE="0 2 * * *"  # Daily at 2 AM

Manual Backup

docker compose exec brrain /brrain backup create --output /backups/manual.tar.gz

Recovery

docker compose exec brrain /brrain backup restore --input /backups/manual.tar.gz

Monitoring

bRRAIn exposes Prometheus metrics at /metrics and health endpoints at /healthz and /readyz. Configure your monitoring stack to scrape these endpoints.

Key metrics to monitor:

  • brrain_memory_store_duration_seconds — Latency for store operations
  • brrain_memory_retrieve_duration_seconds — Latency for retrieve operations
  • brrain_active_connections — Current database connection pool usage
  • brrain_embedding_queue_depth — Pending embedding generation tasks

Upgrades

To upgrade a Docker Compose deployment:

docker compose pull
docker compose up -d
docker compose exec brrain /brrain migrate up

For Kubernetes:

helm upgrade brrain brrain/brrain --namespace brrain --reuse-values --set image.tag=NEW_VERSION

Next Steps