Skip to main content

​
Configuration

Configure your self-hosted Brainz Lab instance.

​
Environment Variables

​
Required (per service)

VariableDescription
SECRET_KEY_BASERails secret key (generate with openssl rand -hex 64)
RAILS_MASTER_KEYRails master key for credentials
DATABASE_URLPostgreSQL connection string
REDIS_URLRedis connection string

​
Optional

VariableDefaultDescription
RAILS_ENVproductionRails environment
RAILS_LOG_LEVELinfoLog level
WEB_CONCURRENCY2Puma workers
RAILS_MAX_THREADS5Threads per worker

​
Traefik Configuration

Traefik provides subdomain-based routing for all services.

​
Access Methods

ServiceTraefik SubdomainDirect Port
Recallrecall.localhostlocalhost:3001
Reflexreflex.localhostlocalhost:3002
Pulsepulse.localhostlocalhost:3003
Traefik Dashboard-localhost:8080

​
Local Development

Add to /etc/hosts: 
127.0.0.1 recall.localhost reflex.localhost pulse.localhost

​
Production Domains

Update traefik/routes.yml for your domain: 
http:
  routers:
    recall:
      rule: "Host(`recall.mycompany.com`)"
      service: recall
      entryPoints:
        - websecure
      tls:
        certResolver: letsencrypt

    reflex:
      rule: "Host(`reflex.mycompany.com`)"
      service: reflex
      entryPoints:
        - websecure
      tls:
        certResolver: letsencrypt

    pulse:
      rule: "Host(`pulse.mycompany.com`)"
      service: pulse
      entryPoints:
        - websecure
      tls:
        certResolver: letsencrypt

​
Enable HTTPS

Add to traefik/traefik.yml: 
entryPoints:
  web:
    address: ":80"
    http:
      redirections:
        entryPoint:
          to: websecure
          scheme: https
  websecure:
    address: ":443"

certificatesResolvers:
  letsencrypt:
    acme:
      email: [email protected]
      storage: /etc/traefik/acme.json
      httpChallenge:
        entryPoint: web

​
Service Configuration

​
Recall (Logging)

VariableDefaultDescription
RECALL_INGEST_KEY-API key for log ingestion
RECALL_BUFFER_SIZE100Logs to buffer before flush
RECALL_FLUSH_INTERVAL5Seconds between flushes
DATABASE_URL=postgres://brainzlab:password@postgres:5432/recall
REDIS_URL=redis://redis:6379/1
RAILS_MASTER_KEY=your_recall_master_key
SECRET_KEY_BASE=your_recall_secret
RECALL_INGEST_KEY=your_ingest_key

​
Reflex (Errors)

VariableDefaultDescription
REFLEX_INGEST_KEY-API key for error capture
REFLEX_MAX_BREADCRUMBS100Breadcrumbs per error
DATABASE_URL=postgres://brainzlab:password@postgres:5432/reflex
REDIS_URL=redis://redis:6379/2
RAILS_MASTER_KEY=your_reflex_master_key
SECRET_KEY_BASE=your_reflex_secret
REFLEX_INGEST_KEY=your_ingest_key

​
Pulse (APM)

VariableDefaultDescription
PULSE_INGEST_KEY-API key for trace ingestion
PULSE_SAMPLE_RATE1.0Trace sampling rate (0.0-1.0)
DATABASE_URL=postgres://brainzlab:password@postgres:5432/pulse
REDIS_URL=redis://redis:6379/3
RAILS_MASTER_KEY=your_pulse_master_key
SECRET_KEY_BASE=your_pulse_secret
PULSE_INGEST_KEY=your_ingest_key

​
Email Configuration

VariableDescription
SMTP_ADDRESSSMTP server address
SMTP_PORTSMTP port (default: 587)
SMTP_USERNAMESMTP username
SMTP_PASSWORDSMTP password
SMTP_FROMFrom email address

​
Retention Settings

VariableDefaultDescription
LOG_RETENTION_DAYS30Days to keep logs
ERROR_RETENTION_DAYS90Days to keep errors
TRACE_RETENTION_DAYS14Days to keep traces

​
Rate Limiting

VariableDefaultDescription
RATE_LIMIT_ENABLEDtrueEnable rate limiting
RATE_LIMIT_REQUESTS1000Requests per minute
RATE_LIMIT_BURST100Burst limit

​
Example .env File

The setup script generates this automatically: 
# PostgreSQL
POSTGRES_USER=brainzlab
POSTGRES_PASSWORD=generated_secure_password
POSTGRES_DB=brainzlab

# Recall
RECALL_MASTER_KEY=generated_key
RECALL_SECRET_KEY=generated_key
RECALL_INGEST_KEY=generated_key

# Reflex
REFLEX_MASTER_KEY=generated_key
REFLEX_SECRET_KEY=generated_key
REFLEX_INGEST_KEY=generated_key

# Pulse
PULSE_MASTER_KEY=generated_key
PULSE_SECRET_KEY=generated_key
PULSE_INGEST_KEY=generated_key

# Optional: Use GitHub Container Registry instead of Docker Hub
# RECALL_IMAGE=ghcr.io/brainz-lab/recall:latest
# REFLEX_IMAGE=ghcr.io/brainz-lab/reflex:latest
# PULSE_IMAGE=ghcr.io/brainz-lab/pulse:latest

​
Client SDK Configuration

Configure your Rails app to connect to your self-hosted instance:
config/initializers/brainzlab.rb
BrainzLab.configure do |config|
  config.secret_key = ENV['BRAINZLAB_SECRET_KEY']

  # Via Traefik subdomains (production)
  config.recall_url = 'https://recall.mycompany.com'
  config.reflex_url = 'https://reflex.mycompany.com'
  config.pulse_url  = 'https://pulse.mycompany.com'

  # Or via direct ports (local development)
  # config.recall_url = 'http://localhost:3001'
  # config.reflex_url = 'http://localhost:3002'
  # config.pulse_url  = 'http://localhost:3003'
end
Or via environment variables: 
# Production (Traefik subdomains)
RECALL_URL=https://recall.mycompany.com
REFLEX_URL=https://reflex.mycompany.com
PULSE_URL=https://pulse.mycompany.com

# Local development (direct ports)
RECALL_URL=http://localhost:3001
REFLEX_URL=http://localhost:3002
PULSE_URL=http://localhost:3003