brk/DOCKER.md

Docker Setup for BRK

This guide explains how to run BRK using Docker and Docker Compose.

Prerequisites

• Docker Engine (with buildx support)
• Docker Compose v2
• A running Bitcoin Core node with RPC enabled
• Access to Bitcoin Core's blocks directory

Quick Start

1. Create environment file

   cp .env.example .env
   

   Edit .env and set BITCOIN_DATA_DIR to your Bitcoin Core data directory.

2. Run with Docker Compose

   docker compose up -d
   

3. Access BRK

   • Web interface: http://localhost:7070
   • API: http://localhost:7070/api

Configuration

Environment Variables

Variable	Description	Default
BITCOIN_DATA_DIR	Path to Bitcoin Core data directory	Required
BTC_RPC_HOST	Bitcoin Core RPC host	localhost
BTC_RPC_PORT	Bitcoin Core RPC port	8332
BRK_SERVICES	Services to run (all, processor, server)	all
BRK_COMPUTATION	Computation mode (lazy, eager)	lazy
BRK_FORMAT	Data format (raw, compressed)	raw
BRK_FETCH	Enable price fetching	true
BRK_MCP	Enable MCP for AI/LLM	true

Service Modes

• all: Run both processor and server (default)
• processor: Only process blockchain data
• server: Only serve API/web interface

Connecting to Bitcoin Core

Option 1: Cookie File Authentication (Recommended)

BRK will automatically use the .cookie file from your Bitcoin Core directory.

Option 2: Username/Password

1. Uncomment the RPC user/password lines in docker-compose.yml
2. Set BTC_RPC_USER and BTC_RPC_PASSWORD in your .env file

Network Connectivity

• Same host:
  • If Bitcoin Core is running natively (not in Docker): Use host.docker.internal on macOS/Windows or 172.17.0.1 on Linux
  • If Bitcoin Core is also in Docker: Use the service name or container IP
• Remote host: Use the actual IP address or hostname

Building the Image

Using Docker Compose (Simple)

docker compose build

Using Docker Build Script

# Build with default settings
./docker-build.sh

# Build with custom tag
./docker-build.sh --tag v1.0.0

Volumes and Data Storage

BRK supports two options for storing its data:

Option 1: Docker Named Volume (Default)

Uses a Docker-managed named volume called brk-data. This is the recommended approach for most users.

Advantages:

• Managed by Docker
• Easy backup/restore
• Platform-independent

Usage: This is the default configuration - no changes needed.

Option 2: Bind Mount

Maps a specific directory on your host to the container's data directory.

Advantages:

• Direct access to files from host
• Easy to locate and manage
• Can be on specific storage devices

Usage:

1. Set BRK_DATA_DIR in your .env file to your desired host directory
2. In docker-compose.yml, comment out the named volume line and uncomment the bind mount line

Example:

# In .env file
BRK_DATA_DIR=/home/user/brk-data

# In docker-compose.yml, uncomment and change as necessary:
      # - ${BRK_DATA_VOLUME:-brk-data}:/home/brk/.brk
      - ${BRK_DATA_DIR:-./brk-data}:/home/brk/.brk

Volume Details

• BRK data: Stores computed datasets, indexes, and application state
• Bitcoin data: Mounted read-only from host (always a bind mount)

Monitoring

View logs:

docker compose logs -f brk

Check status:

docker compose ps

Troubleshooting

Cannot connect to Bitcoin Core

1. Ensure Bitcoin Core is running with -server=1
2. Check RPC credentials are correct
3. Verify network connectivity from container

Permission denied errors

Ensure the Bitcoin data directory is readable by the container user (UID 1000).

Out of memory

Increase Docker's memory limit or use BRK_COMPUTATION=lazy to reduce memory usage.

Security Considerations

• Bitcoin data is mounted read-only for safety
• BRK runs as non-root user inside container
• Only necessary ports are exposed