Mirror/brk
1
0
Fork 0
mirror of https://github.com/bitcoinresearchkit/brk.git synced 2026-05-21 07:14:47 -07:00
Code Issues Packages Projects Releases Wiki Activity

Back to a single image/container setup

Browse Source
This commit is contained in:
deadmanoz
2025-07-04 11:40:37 +08:00
parent d83a833b4d
commit 870c70180f
2 changed files with 47 additions and 102 deletions
Download Patch File Download Diff File Expand all files Collapse all files

102
DOCKER.md
View File

@@ -19,8 +19,7 @@ This guide explains how to run BRK using Docker and Docker Compose.
2. **Run with Docker Compose** 2. **Run with Docker Compose**
```bash ```bash
# Multi-container mode (recommended) docker compose up -d
docker compose up -d brk-processor brk-server
``` ```
3. **Access BRK** 3. **Access BRK**
@@ -28,59 +27,39 @@ This guide explains how to run BRK using Docker and Docker Compose.
- API: http://localhost:7070/api - API: http://localhost:7070/api
- Health check: http://localhost:7070/health - Health check: http://localhost:7070/health
## Deployment Modes ## Architecture
BRK supports flexible deployment modes to suit different use cases: 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
### 1. Multi-Container Mode (Recommended) The container runs the BRK binary with `--services all` to enable both processor and server functionality.
Deploy indexer and server as separate containers. This means the following:
- Better resource isolation
- Independent scaling of components
- Server doesn't need Bitcoin Core or RPC access
- Cleaner failure isolation
- Server can start independently (will serve empty data until processor indexes blocks)
```bash ```bash
# Start both processor and server # Start BRK
docker compose up brk-processor brk-server docker compose up
# Or run in background # Or run in background
docker compose up -d brk-processor brk-server docker compose up -d
```
### 2. Processor-Only Mode
For indexing without web interface:
```bash
docker compose up brk-processor
```
### 3. Server-Only Mode
For serving pre-indexed data:
```bash
docker compose up brk-server
``` ```
## Configuration ## Configuration
### Environment Variables ### Environment Variables
| Variable | Description | Default | Required For | | Variable | Description | Default |
|----------|-------------|---------|-------------| |----------|-------------|---------|
| `BITCOIN_DATA_DIR` | Path to Bitcoin Core data directory | Required | Processor | | `BITCOIN_DATA_DIR` | Path to Bitcoin Core data directory | - |
| `BTC_RPC_HOST` | Bitcoin Core RPC host | `localhost` | Processor | | `BTC_RPC_HOST` | Bitcoin Core RPC host | `localhost` |
| `BTC_RPC_PORT` | Bitcoin Core RPC port | `8332` | Processor | | `BTC_RPC_PORT` | Bitcoin Core RPC port | `8332` |
| `BTC_RPC_USER` | Bitcoin RPC username | - | Processor | | `BTC_RPC_USER` | Bitcoin RPC username | - |
| `BTC_RPC_PASSWORD` | Bitcoin RPC password | - | Processor | | `BTC_RPC_PASSWORD` | Bitcoin RPC password | - |
| `BRK_DATA_VOLUME` | Docker volume name for BRK data | `brk-data` | Both | | `BRK_DATA_VOLUME` | Docker volume name for BRK data | `brk-data` |
| `BRK_COMPUTATION` | Computation mode (`lazy`, `eager`) | `lazy` | Processor | | `BRK_COMPUTATION` | Computation mode (`lazy`, `eager`) | `lazy` |
| `BRK_FORMAT` | Data format (`raw`, `compressed`) | `raw` | Processor | | `BRK_FORMAT` | Data format (`raw`, `compressed`) | `raw` |
| `BRK_FETCH` | Enable price fetching | `true` | Processor | | `BRK_FETCH` | Enable price fetching | `true` |
| `BRK_MCP` | Enable MCP for AI/LLM | `true` | Server | | `BRK_MCP` | Enable MCP for AI/LLM | `true` |
### Example .env File ### Example .env File
@@ -89,7 +68,7 @@ docker compose up brk-server
BITCOIN_DATA_DIR=/path/to/bitcoin/data BITCOIN_DATA_DIR=/path/to/bitcoin/data
BRK_DATA_VOLUME=brk-data BRK_DATA_VOLUME=brk-data
# Bitcoin RPC (required for processor) # Bitcoin RPC configuration
BTC_RPC_HOST=localhost BTC_RPC_HOST=localhost
BTC_RPC_PORT=8332 BTC_RPC_PORT=8332
BTC_RPC_USER=your_username BTC_RPC_USER=your_username
@@ -118,7 +97,7 @@ Set `BTC_RPC_USER` and `BTC_RPC_PASSWORD` in your `.env` file.
## Building the Image ## Building the Image
### Using Docker Compose... ### Using Docker Compose
```bash ```bash
docker compose build docker compose build
``` ```
@@ -152,7 +131,7 @@ BRK_DATA_DIR=/home/user/brk-data
``` ```
```bash ```bash
# In docker-compose.yml, for BOTH the processor and server services. # In docker-compose.yml
# Comment out: # Comment out:
- ${BRK_DATA_VOLUME:-brk-data}:/home/brk/.brk - ${BRK_DATA_VOLUME:-brk-data}:/home/brk/.brk
@@ -170,16 +149,15 @@ volumes:
## Health Checks ## Health Checks
Both containers include health checks: The container includes a combined health check that verifies:
- The BRK process is running
- `brk-processor`: checks that the BRK process is running - The API server is responding on port 3110
- `brk-server`: tests network connectivity on port 3110
## Monitoring ## Monitoring
### Check Container Status ### Check Container Status
```bash ```bash
# View running containers # View running container
docker compose ps docker compose ps
# Check health status # Check health status
@@ -188,14 +166,11 @@ docker compose ps --format \"table {{.Service}}\\t{{.Status}}\\t{{.Health}}\"
### View Logs ### View Logs
```bash ```bash
# View logs from both containers # View logs
docker compose logs brk-processor brk-server docker compose logs
# Follow logs in real-time # Follow logs in real-time
docker compose logs -f brk-processor brk-server docker compose logs -f
# View logs from specific container
docker compose logs -f brk-server
``` ```
## Troubleshooting ## Troubleshooting
@@ -203,12 +178,11 @@ docker compose logs -f brk-server
### Server Issues ### Server Issues
#### Server returns empty data #### Server returns empty data
- This is normal if processor hasn't indexed any blocks yet - This is normal if the processor hasn't indexed any blocks yet
- Server can start before processor and will serve data as it becomes available - The server component will serve data as the processor indexes blocks
- Check that BRK data volume is properly shared between containers
#### Server won't start #### Server won't start
- Check Docker Compose logs: `docker compose logs brk-server` - Check Docker Compose logs: `docker compose logs`
- Verify health endpoint: `curl http://localhost:7070/health` - Verify health endpoint: `curl http://localhost:7070/health`
- Ensure no port conflicts on 7070 - Ensure no port conflicts on 7070
@@ -218,7 +192,7 @@ docker compose logs -f brk-server
1. Ensure Bitcoin Core is running with `-server=1` 1. Ensure Bitcoin Core is running with `-server=1`
2. Check RPC credentials are correct 2. Check RPC credentials are correct
3. Verify network connectivity from container 3. Verify network connectivity from container
4. Test RPC connection: `docker compose exec brk-processor brk --help` 4. Test RPC connection: `docker compose exec brk brk --help`
#### Processor fails to start #### Processor fails to start
- Verify Bitcoin RPC credentials in `.env` - Verify Bitcoin RPC credentials in `.env`
@@ -272,12 +246,12 @@ tar czf brk-backup.tar.gz -C \"$BRK_DATA_DIR\" .
### Restoring BRK Data ### Restoring BRK Data
```bash ```bash
# Stop containers # Stop container
docker compose down docker compose down
# Restore from backup (named volume) # 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 docker run --rm -v brk_brk-data:/target -v \"$(pwd)\":/backup alpine tar xzf /backup/brk-backup.tar.gz -C /target
# Start containers # Start container
docker compose up -d docker compose up -d
``` ```

47
docker-compose.yml
View File

@@ -1,18 +1,20 @@
# BRK multi-container Docker Compose configuration # BRK single-container Docker Compose configuration
services: services:
brk-processor: brk:
build: build:
context: . context: .
dockerfile: Dockerfile dockerfile: Dockerfile
image: brk:latest image: brk:latest
container_name: brk-processor container_name: brk
restart: unless-stopped restart: unless-stopped
ports:
- 7070:3110 # Map host port 7070 to container port 3110
volumes: volumes:
# Bitcoin Core data directory (read-only) # Bitcoin Core data directory (read-only)
# For access to raw block data # For access to raw block data
- ${BITCOIN_DATA_DIR:-/path/to/bitcoin}:/bitcoin:ro - ${BITCOIN_DATA_DIR:-/path/to/bitcoin}:/bitcoin:ro
# BRK data directory for outputs and state (shared with server) # BRK data directory for outputs and state
# Option 1: Use a named volume (default) # Option 1: Use a named volume (default)
- ${BRK_DATA_VOLUME:-brk-data}:/home/brk/.brk - ${BRK_DATA_VOLUME:-brk-data}:/home/brk/.brk
# Option 2: Use a bind mount (uncomment and set BRK_DATA_DIR in .env) # Option 2: Use a bind mount (uncomment and set BRK_DATA_DIR in .env)
@@ -36,6 +38,7 @@ services:
- COMPUTATION=${BRK_COMPUTATION:-lazy} - COMPUTATION=${BRK_COMPUTATION:-lazy}
- FORMAT=${BRK_FORMAT:-raw} - FORMAT=${BRK_FORMAT:-raw}
- FETCH=${BRK_FETCH:-true} - FETCH=${BRK_FETCH:-true}
- MCP=${BRK_MCP:-true}
command: command:
- --bitcoindir - --bitcoindir
- /bitcoin - /bitcoin
@@ -48,46 +51,14 @@ services:
- --rpcpassword - --rpcpassword
- "${BTC_RPC_PASSWORD:-bitcoin}" - "${BTC_RPC_PASSWORD:-bitcoin}"
- --services - --services
- processor - all
healthcheck: healthcheck:
test: ["CMD", "pgrep", "-f", "brk"] test: ["CMD", "sh", "-c", "pgrep -f brk && nc -z localhost 3110"]
interval: 30s interval: 30s
timeout: 10s timeout: 10s
retries: 3 retries: 3
start_period: 60s start_period: 60s
brk-server:
build:
context: .
dockerfile: Dockerfile
image: brk:latest
container_name: brk-server
restart: unless-stopped
ports:
- 7070:3110 # Map host port 7070 to container port 3110
volumes:
# BRK data directory (shared with processor)
# Option 1: Use a named volume (default)
- ${BRK_DATA_VOLUME:-brk-data}:/home/brk/.brk
# Option 2: Use a bind mount (uncomment and set BRK_DATA_DIR in .env)
# - ${BRK_DATA_DIR:-./brk-data}:/home/brk/.brk
environment:
# BRK configuration (server doesn't need Bitcoin RPC)
- BRKDIR=/home/brk/.brk
- MCP=${BRK_MCP:-true}
command:
- --brkdir
- /home/brk/.brk
- --services
- server
# Note: Server can start without processor, will serve empty data until processor indexes blocks
healthcheck:
test: ["CMD", "sh", "-c", "nc -z localhost 3110 || exit 1"]
interval: 30s
timeout: 10s
retries: 3
start_period: 30s
volumes: volumes:
brk-data: brk-data:
driver: local driver: local