mirror of
https://github.com/bitcoinresearchkit/brk.git
synced 2026-05-15 02:58:36 -07:00
153 lines
4.0 KiB
Markdown
153 lines
4.0 KiB
Markdown
# 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**
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
Edit `.env` and set `BITCOIN_DATA_DIR` to your Bitcoin Core data directory.
|
|
|
|
2. **Run with Docker Compose**
|
|
```bash
|
|
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)
|
|
```bash
|
|
docker compose build
|
|
```
|
|
|
|
### Using Docker Build Script
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# In .env file
|
|
BRK_DATA_DIR=/home/user/brk-data
|
|
```
|
|
|
|
```yaml
|
|
# 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:
|
|
```bash
|
|
docker compose logs -f brk
|
|
```
|
|
|
|
Check status:
|
|
```bash
|
|
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
|