Skip to content

Creating a Custom Deployment

Create a new deployment from the bigbrotr base with custom configuration, schema, and Docker settings.

Overview

BigBrotr ships with two deployments: bigbrotr (full event archive) and lilbrotr (lightweight, tags/content/sig present but NULL). To create your own, copy bigbrotr and customize. Each deployment is a self-contained directory with configuration, SQL schema, Docker Compose, and monitoring files.

Step 1: Copy the Template

cp -r deployments/bigbrotr deployments/myproject
cd deployments/myproject

Step 2: Configure Docker Compose

Edit docker-compose.yaml:

  1. Update container name prefixes (e.g., myproject-postgres)
  2. Set unique port mappings to avoid conflicts with existing deployments
  3. Update the database name in service environment variables
  4. Set the DEPLOYMENT build argument:
services:
  finder:
    build:
      context: ../..
      dockerfile: deployments/Dockerfile
      args:
        DEPLOYMENT: myproject

Step 3: Configure the Database Connection

Edit config/brotr.yaml with shared connection settings:

pool:
  database:
    host: pgbouncer       # Use 'localhost' for manual deployment
    database: myproject    # Your database name

Per-service pool settings (user, password, pool sizing) are configured in each service's YAML file. See Step 4.

Step 4: Customize Service Configs

Edit files in config/services/. Each service config includes a pool: section for per-service database role and pool sizing:

# config/services/finder.yaml
pool:
  user: myproject_writer           # Database role for this service
  password_env: DB_WRITER_PASSWORD # Env var with the role's password
  min_size: 1
  max_size: 3

# ... service-specific config below

Service files to customize:

  • seeder.yaml -- seed file path and insertion mode
  • finder.yaml -- discovery interval, API sources, event kinds
  • validator.yaml -- validation interval, network settings
  • monitor.yaml -- health check settings, publishing relays
  • synchronizer.yaml -- sync interval, concurrency, event filters
  • refresher.yaml -- materialized view refresh interval and view list
  • api.yaml -- REST API host, port, table access policies
  • dvm.yaml -- Nostr relays, table policies, NIP-90 kind

Tip

See the Configuration reference for all available fields and their defaults.

Step 5: Choose a Schema

Edit postgres/init/02_tables.sql to select which schema to use:

Keep the full event table with all columns (tags, content, sig). This stores complete Nostr events and enables the 11 materialized views.

Use the lightweight event table with all 8 columns where tags, content, and sig are nullable and always NULL. This provides approximately 60% disk savings since NULL values do not occupy storage. All 11 materialized views are still available.

Step 6: Set Up the Seed File

Edit static/seed_relays.txt with your initial relay URLs (one per line):

wss://relay.damus.io
wss://relay.nostr.band
wss://nos.lol

Step 7: Create the Environment File

cp .env.example .env
# Edit .env: set DB_ADMIN_PASSWORD, DB_WRITER_PASSWORD, DB_REFRESHER_PASSWORD, DB_READER_PASSWORD, NOSTR_PRIVATE_KEY, GRAFANA_PASSWORD
chmod 600 .env

Step 8: Build and Start

# Build the Docker image with your deployment name
docker compose build

# Start the stack
docker compose up -d

# Verify
docker compose ps
docker compose logs -f seeder

Step 9: Test the Deployment

# Check that the database schema was applied
docker compose exec postgres psql -U admin -d myproject -c "\dt"

# Verify roles were created
docker compose exec postgres psql -U admin -d myproject -c \
    "SELECT rolname FROM pg_roles WHERE rolname LIKE 'myproject_%'"

# Check that the seeder populated candidates
docker compose logs seeder

# Verify services are healthy
docker compose ps

Note

If you need to reset and start fresh, run docker compose down -v to remove all containers and volumes, then docker compose up -d again.