Docker Setup for BRK

Prerequisites

Docker Engine (with buildx support)
Docker Compose v2
A running Bitcoin Core node with RPC enabled

Quick Start

Create environment file
```
cp docker/.env.example docker/.env
```
Edit docker/.env and set BITCOIN_DATA_DIR to your Bitcoin Core data directory.

Run with Docker Compose

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

Access BRK
- Web interface: http://localhost:7070
- API: http://localhost:7070/api
- Health check: http://localhost:7070/health

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_USER`	Bitcoin RPC username	`bitcoin`
`BTC_RPC_PASSWORD`	Bitcoin RPC password	`bitcoin`
`BRK_DATA_VOLUME`	Docker volume name for BRK data	`brk-data`

Connecting to Bitcoin Core

Cookie File Authentication (Recommended) Uncomment the --rpccookiefile lines in docker-compose.yml and remove --rpcuser/--rpcpassword.

Username/Password Set BTC_RPC_USER and BTC_RPC_PASSWORD in your docker/.env file.

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

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

Data Storage

BRK uses sparse files. Volume inspection and docker system df may report the logical file size (>1 TB) instead of actual disk usage (~350 GB). Use du -sh on the volume mount point to see real usage.

Named Volume (Default)

Uses a Docker-managed volume called brk-data.

Bind Mount

Set BRK_DATA_DIR in docker/.env
In docker-compose.yml, comment out the named volume line and uncomment the bind mount line
Remove the volumes: section at the bottom of docker-compose.yml

Monitoring

docker compose -f docker/docker-compose.yml ps
docker compose -f docker/docker-compose.yml logs -f

Troubleshooting

Cannot connect to Bitcoin Core

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

Permission denied errors

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

Security

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