Brainz Lab Stack

Self-hosted observability platform for Rails applications.

Overview

Brainz Lab provides complete observability for your Rails apps:

• Recall - Structured logging with powerful search
• Reflex - Error tracking with smart grouping
• Pulse - APM with distributed tracing

Quick Install

curl -fsSL https://raw.githubusercontent.com/brainz-lab/stack/main/install.sh | bash

Or manually:

git clone https://github.com/brainz-lab/stack.git
cd stack
./scripts/setup.sh
./scripts/start.sh

Requirements

• Docker & Docker Compose
• 2GB RAM minimum (4GB recommended)

Services

Service	Port	Description
Recall	3001	Structured logging
Reflex	3002	Error tracking
Pulse	3003	APM & tracing

Usage

Start

./scripts/start.sh

Stop

./scripts/stop.sh

View Logs

./scripts/logs.sh          # All services
./scripts/logs.sh recall   # Single service

Reset Data

./scripts/reset.sh

Integrate with Your App

1. Add the SDK

# Gemfile
gem 'brainzlab'

2. Configure

# config/initializers/brainzlab.rb
BrainzLab.configure do |config|
  config.secret_key = ENV['BRAINZLAB_SECRET_KEY']

  # Self-hosted URLs (via Traefik subdomains)
  config.recall_url = ENV['RECALL_URL']  # http://recall.localhost or https://recall.yourdomain.com
  config.reflex_url = ENV['REFLEX_URL']  # http://reflex.localhost or https://reflex.yourdomain.com
  config.pulse_url  = ENV['PULSE_URL']   # http://pulse.localhost or https://pulse.yourdomain.com
end

Tip: Run ./scripts/setup.sh to generate keys and optionally export URLs to your shell profile.

3. Use

# Logging
BrainzLab::Recall.info("User signed up", user_id: user.id)

# Error tracking (automatic in Rails, or manual)
BrainzLab::Reflex.capture(exception, user: current_user)

# APM (automatic instrumentation)
# Just install the gem and it works!

# Custom metrics
BrainzLab::Pulse.increment("orders.created")
BrainzLab::Pulse.gauge("queue.size", Sidekiq::Queue.new.size)

Configuration

Copy .env.example to .env and customize:

cp .env.example .env

Key Settings

Variable	Description	Default
POSTGRES_PASSWORD	Database password	brainzlab
RECALL_PORT	Recall port	3001
REFLEX_PORT	Reflex port	3002
PULSE_PORT	Pulse port	3003

Using GitHub Container Registry

To use GHCR 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

Production Deployment

For production, we recommend:

1. Use a managed database (RDS, Cloud SQL, etc.)
2. Set up HTTPS with a reverse proxy (nginx, Traefik, Caddy)
3. Configure proper secrets in .env
4. Set up backups for PostgreSQL

Environment Variables for Production

# Required
POSTGRES_PASSWORD=<strong-password>
RECALL_MASTER_KEY=<generated-key>
REFLEX_MASTER_KEY=<generated-key>
PULSE_MASTER_KEY=<generated-key>
BRAINZLAB_SECRET_KEY=<generated-key>

# URLs (Traefik subdomains - your domain)
RECALL_URL=https://recall.yourdomain.com
REFLEX_URL=https://reflex.yourdomain.com
PULSE_URL=https://pulse.yourdomain.com

DNS Configuration

Set up DNS records for your Traefik subdomains:

recall.yourdomain.com  → Your server IP
reflex.yourdomain.com  → Your server IP
pulse.yourdomain.com   → Your server IP

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        Your Rails App                            │
│                                                                  │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                    brainzlab gem                         │    │
│  │  Recall (logs) │ Reflex (errors) │ Pulse (traces)       │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Brainz Lab Stack                            │
│                                                                  │
│       ┌──────────┐    ┌──────────┐    ┌──────────┐             │
│       │  Recall  │    │  Reflex  │    │  Pulse   │             │
│       │  :3001   │    │  :3002   │    │  :3003   │             │
│       └────┬─────┘    └────┬─────┘    └────┬─────┘             │
│            │               │               │                    │
│       ┌────┴───────────────┴───────────────┴────┐              │
│       │          PostgreSQL + Redis              │              │
│       └──────────────────────────────────────────┘              │
└─────────────────────────────────────────────────────────────────┘

Documentation

Full documentation: docs.brainzlab.ai/self-hosting

Related

• brainzlab-ruby - Ruby SDK
• Recall - Logging service
• Reflex - Error tracking service
• Pulse - APM service

License

MIT