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

computer: snapshot

Browse Source
This commit is contained in:
nym21
2026-02-26 23:01:51 +01:00
parent cccaf6b206
commit 78fc5ffcf7
69 changed files with 1578 additions and 2205 deletions
Download Patch File Download Diff File Expand all files Collapse all files

68
docker/.dockerignore
View File

@@ -1,68 +0,0 @@
# Git
.git
.gitignore
# Build artifacts
target/
# Development files
.vscode/
.idea/
*.swp
*.swo
*~
# OS files
.DS_Store
Thumbs.db
# Docker files
Dockerfile
docker-compose.yml
.dockerignore
docker-build.sh
# Documentation
docs/
LICENSE
# Keep README.md for build process
!README.md
# CI/CD
.github/
# Logs and temporary files
*.log
tmp/
temp/
# BRK runtime data (should be in volumes)
.brk/
# Example and test data
examples/
tests/
*.test
*.example
# Node modules (if any frontend deps)
node_modules/
# Python cache (if any)
__pycache__/
*.pyc
*.pyo
# Rust workspace cache
**/*.rs.bk
# macOS
.AppleDouble
.LSOverride
# Windows
Desktop.ini
ehthumbs.db
# Linux
.directory

25
docker/.env.example
View File

@@ -1,29 +1,4 @@
# Bitcoin Core data directory
# This should point to your Bitcoin Core data directory
BITCOIN_DATA_DIR=/path/to/bitcoin
# Bitcoin Core RPC configuration
# If running Bitcoin Core on the same host (not in Docker), use host.docker.internal on macOS/Windows
# or the host's IP address on Linux
BTC_RPC_HOST=localhost
BTC_RPC_PORT=8332
# Use either cookie file authentication (recommended) or username/password
# Cookie file is automatically created by Bitcoin Core
# If using username/password, comment out RPCCOOKIEFILE in docker-compose.yml
# BTC_RPC_USER=your_rpc_username
# BTC_RPC_PASSWORD=your_rpc_password
# Enable price fetching from exchanges
BRK_FETCH=true
# BRK data storage options
# Option 1: Use a Docker named volume (default, recommended)
# This is the default configuration - no changes needed.
# Leave this commented to use the default named volume
# BRK_DATA_VOLUME=brk-data
# Option 2: Use a bind mount to a local directory
# Uncomment and set this to use a specific directory on your host
# Also uncomment the corresponding line in docker-compose.yml
# BRK_DATA_DIR=/path/to/brk/data

39
docker/Dockerfile
View File

@@ -1,57 +1,28 @@
# *************
# Builder
# *************
FROM rustlang/rust:nightly AS builder
FROM rust:1.93-bookworm AS builder
# Install build dependencies
RUN apt-get update && apt-get install -y \
pkg-config \
libssl-dev \
build-essential \
&& rm -rf /var/lib/apt/lists/*
RUN apt-get update && apt-get install -y pkg-config libssl-dev && rm -rf /var/lib/apt/lists/*
WORKDIR /app
# Copy all source files
COPY . .
COPY Cargo.toml Cargo.lock rust-toolchain.toml ./
COPY crates crates
# Build the application
RUN cargo build --release --locked
# *************
# Runtime
# *************
FROM debian:bookworm-slim
# Install runtime dependencies
RUN apt-get update && apt-get install -y \
ca-certificates \
openssl \
&& rm -rf /var/lib/apt/lists/*
RUN apt-get update && apt-get install -y ca-certificates curl && rm -rf /var/lib/apt/lists/*
# Create non-root user
RUN useradd -m -s /bin/bash brk
# Copy binary from builder
COPY --from=builder /app/target/release/brk /usr/local/bin/brk
# Copy websites directory
COPY --from=builder /app/websites /app/websites
# Set ownership
RUN chown -R brk:brk /app
# Switch to non-root user
USER brk
# Create directories for BRK data
RUN mkdir -p /home/brk/.brk
# Expose API port
EXPOSE 3110
# Set working directory
WORKDIR /home/brk
# Default entrypoint
ENTRYPOINT ["brk"]

210
docker/README.md
View File

@@ -1,13 +1,10 @@
# 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
@@ -22,232 +19,75 @@ This guide explains how to run BRK using Docker and Docker Compose.
docker compose -f docker/docker-compose.yml up -d
```
Or from the docker directory:
```bash
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
```bash
# 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
All configuration is passed via CLI args in `docker-compose.yml`. Edit the `command:` section to change settings.
### Environment Variables
These variables are interpolated into `docker-compose.yml` at startup:
| 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 | - |
| `BTC_RPC_USER` | Bitcoin RPC username | `bitcoin` |
| `BTC_RPC_PASSWORD` | Bitcoin RPC password | `bitcoin` |
| `BRK_DATA_VOLUME` | Docker volume name for BRK data | `brk-data` |
### Example .env File
```env
# 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
```
### Connecting to Bitcoin Core
#### Option 1: Cookie File Authentication (Recommended)
BRK will automatically use the `.cookie` file from your Bitcoin Core directory.
**Cookie File Authentication (Recommended)**
Uncomment the `--rpccookiefile` lines in `docker-compose.yml` and remove `--rpcuser`/`--rpcpassword`.
#### Option 2: Username/Password
**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
**Network Connectivity**
- **Same host (Bitcoin Core running natively)**: Use `host.docker.internal` on macOS/Windows or `172.17.0.1` on Linux
- **Same host (Bitcoin Core in Docker)**: Use the service name or container IP
- **Remote host**: Use the actual IP address or hostname
## Building the Image
## Building
### Using Docker Compose
```bash
docker compose -f docker/docker-compose.yml build
```
### or ... Using Docker Build Script
```bash
# Build with default settings
./docker/docker-build.sh
## Data Storage
# Build with custom tag
./docker/docker-build.sh --tag v1.0.0
```
### Named Volume (Default)
Uses a Docker-managed volume called `brk-data`.
## 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
```bash
# In docker/.env file
BRK_DATA_DIR=/home/user/brk-data
```
```bash
# 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):
```bash
# 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 (port 7070 externally, 3110 internally)
### Bind Mount
1. Set `BRK_DATA_DIR` in `docker/.env`
2. In `docker-compose.yml`, comment out the named volume line and uncomment the bind mount line
3. Remove the `volumes:` section at the bottom of `docker-compose.yml`
## Monitoring
### Check Container Status
```bash
# 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
```bash
# 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
### 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)
### Permission denied errors
Ensure the Bitcoin data directory is readable by the container user (UID 1000).
### Performance Issues
## Security
#### 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
- Bitcoin data is mounted read-only
- BRK runs as non-root user inside container
- Only necessary ports are exposed
## Backup and Recovery
### Backing Up BRK Data
```bash
# 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
```bash
# 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
```

77
docker/docker-build.sh
View File

@@ -1,77 +0,0 @@
#!/bin/bash
set -e
# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color
# Default values
IMAGE_NAME="brk"
TAG="latest"
# Function to print colored output
print_info() {
echo -e "${GREEN}[INFO]${NC} $1"
}
print_warn() {
echo -e "${YELLOW}[WARN]${NC} $1"
}
print_error() {
echo -e "${RED}[ERROR]${NC} $1"
}
# Parse command line arguments
while [[ $# -gt 0 ]]; do
case $1 in
-t|--tag)
TAG="$2"
shift 2
;;
-h|--help)
echo "Usage: $0 [OPTIONS]"
echo ""
echo "Options:"
echo " -t, --tag TAG Tag for the image (default: latest)"
echo " -h, --help Show this help message"
exit 0
;;
*)
print_error "Unknown option: $1"
exit 1
;;
esac
done
# Build the image
print_info "Building BRK Docker image..."
print_info "Image: ${IMAGE_NAME}:${TAG}"
# Detect script location and set paths accordingly
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
# Determine if we're running from project root or docker directory
if [[ "$(basename "$PWD")" == "docker" ]]; then
# Running from docker directory
DOCKERFILE_PATH="./Dockerfile"
BUILD_CONTEXT=".."
print_info "Running from docker directory"
else
# Running from project root or elsewhere
DOCKERFILE_PATH="docker/Dockerfile"
BUILD_CONTEXT="."
print_info "Running from project root"
fi
# Execute the build
if docker build -f "$DOCKERFILE_PATH" -t "${IMAGE_NAME}:${TAG}" "$BUILD_CONTEXT"; then
print_info "Build completed successfully!"
print_info "Image built as ${IMAGE_NAME}:${TAG}"
else
print_error "Build failed!"
exit 1
fi

34
docker/docker-compose.yml
View File

@@ -1,5 +1,3 @@
# BRK single-container Docker Compose configuration
name: brk
services:
@@ -11,36 +9,17 @@ services:
container_name: brk
restart: unless-stopped
ports:
- 7070:3110 # Map host port 7070 to container port 3110
- 7070:3110
volumes:
# Bitcoin Core data directory (read-only)
# For access to raw block data
- ${BITCOIN_DATA_DIR:-/path/to/bitcoin}:/bitcoin:ro
# BRK data directory for outputs and state
# 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)
# Bind mount alternative (uncomment and set BRK_DATA_DIR in .env):
# - ${BRK_DATA_DIR:-./brk-data}:/home/brk/.brk
environment:
# Bitcoin Core configuration
- BITCOINDIR=/bitcoin
- BLOCKSDIR=/bitcoin/blocks
# RPC configuration (required for processor)
- RPCCONNECT=${BTC_RPC_HOST:-localhost}
- RPCPORT=${BTC_RPC_PORT:-8332}
# - RPCCOOKIEFILE=/bitcoin/.cookie
# Username/password authentication
- RPCUSER=${BTC_RPC_USER}
- RPCPASSWORD=${BTC_RPC_PASSWORD}
# BRK configuration
- BRKDIR=/home/brk/.brk
- FETCH=${BRK_FETCH:-true}
command:
- --bitcoindir
- /bitcoin
- --blocksdir
- /bitcoin/blocks
- --brkdir
- /home/brk/.brk
- --rpcconnect
@@ -49,8 +28,11 @@ services:
- "${BTC_RPC_USER:-bitcoin}"
- --rpcpassword
- "${BTC_RPC_PASSWORD:-bitcoin}"
# Cookie file alternative (uncomment and remove rpcuser/rpcpassword above):
# - --rpccookiefile
# - /bitcoin/.cookie
healthcheck:
test: ["CMD", "sh", "-c", "pgrep -f brk && nc -z localhost 3110"]
test: ["CMD", "curl", "-sf", "http://localhost:3110/health"]
interval: 30s
timeout: 10s
retries: 3