brk/docker/README.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 docker/.env.example docker/.env
   

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

2. Run with Docker Compose

   docker compose -f docker/docker-compose.yml up -d
   

   Or from the docker directory:

   cd docker && docker compose up -d
   

3. Access BRK

   • Web interface: http://localhost:7070
   • API: http://localhost:7070/api
   • Health check: http://localhost:7070/health

Architecture

BRK runs as a single container that includes both the blockchain processor and API server. This simplified architecture:

• Ensures processor and server are always in sync
• Simplifies deployment and monitoring
• Uses a single shared data directory

# Start BRK
docker compose -f docker/docker-compose.yml up

# Or run in background
docker compose -f docker/docker-compose.yml up -d

# Alternative: from docker directory
cd docker && docker compose up -d

Configuration

Environment Variables

Variable	Description	Default
BITCOIN_DATA_DIR	Path to Bitcoin Core data directory	-
BTC_RPC_HOST	Bitcoin Core RPC host	localhost
BTC_RPC_PORT	Bitcoin Core RPC port	8332
BTC_RPC_USER	Bitcoin RPC username	-
BTC_RPC_PASSWORD	Bitcoin RPC password	-
BRK_DATA_VOLUME	Docker volume name for BRK data	brk-data
BRK_FETCH	Enable price fetching	true
BRK_MCP	Enable MCP for AI/LLM	true

Example .env File

# Bitcoin Core paths
BITCOIN_DATA_DIR=/path/to/bitcoin/data
BRK_DATA_VOLUME=brk-data

# Bitcoin RPC configuration
BTC_RPC_HOST=localhost
BTC_RPC_PORT=8332
BTC_RPC_USER=your_username
BTC_RPC_PASSWORD=your_password

# BRK settings
BRK_FETCH=true
BRK_MCP=true

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

Set BTC_RPC_USER and BTC_RPC_PASSWORD in your docker/.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

docker compose -f docker/docker-compose.yml build

or ... Using Docker Build Script

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

# Build with custom tag
./docker/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.

Option 2: Bind Mount

Maps a specific directory on your host to the container's data directory. This may be desirable if you want to use a specific storage location for BRK data (e.g. a different disk).

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

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

# In docker/docker-compose.yml
# Comment out:
   - ${BRK_DATA_VOLUME:-brk-data}:/home/brk/.brk

# Uncomment:
   # - ${BRK_DATA_DIR:-./brk-data}:/home/brk/.brk

Can also remove or comment out the volumes section from the docker/docker-compose.yml file (right at the bottom):

# Comment out:
volumes:
  brk-data:
    driver: local

Health Checks

The container includes a combined health check that verifies:

• The BRK process is running
• The API server is responding on port 3110

Monitoring

Check Container Status

# View running container
docker compose -f docker/docker-compose.yml ps

# Check health status
docker compose -f docker/docker-compose.yml ps --format \"table {{.Service}}\\t{{.Status}}\\t{{.Health}}\"

View Logs

# View logs
docker compose -f docker/docker-compose.yml logs

# Follow logs in real-time
docker compose -f docker/docker-compose.yml logs -f

Troubleshooting

Server Issues

Server returns empty data

• This is normal if the processor hasn't indexed any blocks yet
• The server component will serve data as the processor indexes blocks

Server won't start

• Check Docker Compose logs: docker compose -f docker/docker-compose.yml logs
• Verify health endpoint: curl http://localhost:7070/health
• Ensure no port conflicts on 7070

Processor Issues

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
4. Test RPC connection: docker compose -f docker/docker-compose.yml exec brk brk --help

Processor fails to start

• Verify Bitcoin RPC credentials in docker/.env
• Ensure Bitcoin Core is running and accessible
• Check Bitcoin data directory permissions (should be readable by UID 1000)

Performance Issues

Slow indexing

• Ensure adequate disk space for indexed data - a minimum of 3GB/s is recommended
• Monitor memory usage during initial indexing

Out of memory

• Increase Docker's memory limit
• Monitor container resource usage: docker stats

Permission Issues

Permission denied errors

• Ensure the Bitcoin data directory is readable by the container user (UID 1000)
• Check that volumes are properly mounted
• Verify file ownership: ls -la $BITCOIN_DATA_DIR

Network Issues

Cannot access web interface

• Verify port mapping: docker compose -f docker/docker-compose.yml ps
• Check firewall settings
• Ensure no other services are using port 7070

Security Considerations

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

Backup and Recovery

Backing Up BRK Data

# Create backup of named volume
docker run --rm -v brk_brk-data:/source -v \"$(pwd)\":/backup alpine tar czf /backup/brk-backup.tar.gz -C /source .

# Or if using bind mount
tar czf brk-backup.tar.gz -C \"$BRK_DATA_DIR\" .

Restoring BRK Data

# Stop container
docker compose -f docker/docker-compose.yml down

# Restore from backup (named volume)
docker run --rm -v brk_brk-data:/target -v \"$(pwd)\":/backup alpine tar xzf /backup/brk-backup.tar.gz -C /target

# Start container
docker compose -f docker/docker-compose.yml up -d