Bitcoin Docker Node Guide

Operations-focused guide for running Bitcoin Core via Docker Compose. Troubleshooting for stuck containers, LevelDB corruption, RPC connectivity. For the full Korean version see README.md. For RPC and external access details see RPC.md.

Native host install: ../localhost/README.md
Bitcoin Core docs: https://bitcoincore.org/en/doc/
RPC reference: https://developer.bitcoin.org/reference/rpc/

Important: docker-compose.yml may be configured to expose RPC (8332) on all interfaces. If you do not need external RPC, bind to 127.0.0.1:8332:8332 or restrict with rpcallowip and the host firewall (UFW).

Quick start

1) Host data directory

sudo mkdir -p /mnt/cryptocur-data/bitcoin

# align permissions to the container's bitcoin user UID
BITCOIN_UID=$(docker run --rm docker_bitcoind id -u bitcoin)
sudo chown -R $BITCOIN_UID:$BITCOIN_UID /mnt/cryptocur-data/bitcoin
sudo chmod -R 755 /mnt/cryptocur-data/bitcoin

2) Configuration

cd ~/blockchain-node-guides/chains/bitcoin/docker
cp bitcoin.conf.example bitcoin.conf
nano bitcoin.conf

Required: set a strong rpcpassword.
Manage RPC credentials in a single place — either bitcoin.conf or docker-compose.yml environment variables — to avoid conflicts. See RPC.md.

3) Run / stop

cd ~/blockchain-node-guides/chains/bitcoin/docker

# start (build included)
docker-compose up -d

# logs
docker-compose logs -f

# stop and clean up
docker-compose down

Operational checklist

Container status & resources

docker ps -a
docker stats bitcoin-node
docker logs -f bitcoin-node

Health checks

docker-compose exec bitcoind bitcoin-cli getblockchaininfo
docker-compose exec bitcoind bitcoin-cli getnetworkinfo
docker-compose exec bitcoind bitcoin-cli getconnectioncount
docker inspect --format='{{json .State.Health}}' bitcoin-node | jq

Cookie-file health checks (-rpccookiefile=/home/bitcoin/.bitcoin/.cookie) are the most reliable — they survive RPC password rotation.

Common problems

`docker-compose down` fails with `permission denied`

cd ~/blockchain-node-guides/chains/bitcoin/docker

# Retry with sudo first
sudo docker-compose down

# Then stop the container manually
sudo docker stop bitcoin-node || true
sudo docker rm -f bitcoin-node || true

# If the project network is stuck
sudo docker network ls | grep -i bitcoin
sudo docker network rm docker_bitcoin-network  # example

# Snap Docker needs a restart once in a while
sudo snap restart docker

`Cannot obtain a lock on data directory`

Another bitcoind is running against the same data directory, or a stale lock remains after an abnormal shutdown.

# 1) check other bitcoind processes
docker ps -a | grep -i bitcoin
ps -ef | grep -E '[b]itcoind'

# 2) stop cleanly
cd ~/blockchain-node-guides/chains/bitcoin/docker
docker-compose down

# 3) remove stale locks (only when bitcoind is fully stopped)
sudo rm -f /mnt/cryptocur-data/bitcoin/.lock
sudo rm -f /mnt/cryptocur-data/bitcoin/bitcoind.pid

# 4) restart
docker-compose up -d
docker logs -f bitcoin-node

LevelDB corruption

Use -reindex-chainstate (or -reindex for a full reindex). Remove the flag after recovery completes.

Metrics endpoint (Prometheus)

bitcoind does not expose Prometheus metrics natively. Attach the community exporter:

bitcoin-prometheus-exporter → default port 9332

services:
  bitcoin-exporter:
    image: jvstein/bitcoin-prometheus-exporter:latest
    container_name: bitcoin-exporter
    restart: unless-stopped
    environment:
      BITCOIN_RPC_HOST: bitcoind
      BITCOIN_RPC_PORT: 8332
      BITCOIN_RPC_USER: ${BITCOIN_RPC_USER}
      BITCOIN_RPC_PASSWORD: ${BITCOIN_RPC_PASSWORD}
    ports:
      - "127.0.0.1:9332:9332"

Monitoring stack details: ../../../common/monitoring-stack.md.

Directory layout

README.md — Korean operations/troubleshooting guide
README.en.md — this file (English)
RPC.md — RPC / curl / security / external access