lnliz/bitcoind repository overview

⁠lnliz/bitcoind

This repo builds bitcoind⁠ in an auditable way⁠, and packages it into a minimal Docker containers provided for various CPU architectures.

⁠Available Versions

⁠Latest version

• knots-latest (latest current version of Bitcoin Knots)
• core-latest (latest current version of Bitcoin Core)
• inq-latest (latest current version of Bitcoin Inquisition)

⁠Specific version

• v31.1 (most current)
• v31.0
• v30.3 (most current 30.x)
• v30.2
• v29.4.inq (inquisition⁠ - most current)
• v29.2.inq
• v29.1.inq
• v29.4.1.knots20260508 (knots⁠ - most current)
• (v29.4.1.knots20260508 is not compatible with previous version because of change in hashong algorithm)
• v29.4.knots20260508
• v29.3.knots20260508
• v29.3.knots20260210
• v29.2.knots20251110
• v29.4 (most current 29.x)
• v29.3
• v29.2
• v29.1
• v29.0
• v28.4 (most current 28.x)
• v28.3
• v28.2
• v28.1
• v28.0
• v27.2

⁠Usage

⁠Pull

First pull the image from Docker Hub⁠:

docker pull lnliz/bitcoind:v31.1

Or, to pull a specific CPU architecture:

docker pull lnliz/bitcoind:v31.1-arm64v8

⁠Start

First of all, create a directory in your home directory called .bitcoin

Next, create a config file. You can take a look at the following sample: thebox-compose-system (1⁠).

Some guides on how to configure bitcoin can be found here⁠ (bitcoin git repo)

Then to start bitcoind, run:

docker run  -it  --rm  --detach \
    -v ~/.bitcoin:/data/.bitcoin \
    -p 8332:8332 \
    -p 8333:8333 \
    -p 28332:28332 \
    -p 28333:28333 \
    --name bitcoind \
    lnliz/bitcoind:v31.1

That will run bitcoind such that:

• all data generated by the container is stored in ~/.bitcoin on your host machine,
• port 8332 will be reachable for the RPC communication,
• port 8333 will be reachable for the peer-to-peer communication,
• port 28332 will be reachable for ZMQ block notifications,
• port 28333 will be reachable for ZMQ transaction notifications,
• created container will get named bitcoind,
• within the container, bitcoind binary is run as unprivileged user bitcoind (UID=1000),
• that command will run the container in the background and print the ID of the container being run.

⁠Bitcoin Inquisition

You can also use Bitcoin Inquisition⁠ by using different image tag:

docker pull lnliz/bitcoind:v29.4.inq

⁠Knots

You can also use Bitcoin Knots⁠ by using different image tag:

docker pull lnliz/bitcoind:v29.1.knots20250903

⁠Interact

To issue any commands to a running container, do:

docker exec -it bitcoind BINARY COMMAND

Where:

• BINARY is either bitcoind, bitcoin-cli, bitcoin-tx, (or bitcoin-wallet on v0.18+) and
• COMMAND is something you'd normally pass to the binary

Examples:

docker exec -it bitcoind bitcoind --help
docker exec -it bitcoind bitcoind --version
docker exec -it bitcoind bitcoin-cli --help
docker exec -it bitcoind bitcoin-cli -getinfo
docker exec -it bitcoind bitcoin-cli getblockcount

⁠Docker Compose

Here is a docker-compose.yml for mainnet

version: '3'
services:
  bitcoin:
    container_name: bitcoind
    user: 1000:1000
    image: lnliz/bitcoind:v31.1
    volumes:
      - ./bitcoin:/data/.bitcoin
    restart: on-failure
    stop_grace_period: 15m30s
    ports:
      - "8333:8333"
      - "8332:8332"
      - "28332:28332"
      - "28333:28333"

First, ensure that the bitcoin/ folder is in the directory containing docker-compose.yml. Then, Docker Compose will mount the bitcoin/ folder to /data/.bitcoin.

⁠Details

• All builds aim to be maximally auditable. After git tag push, the entire process is automated, with each step printed, and the code aiming to be easy to follow
• All builds are based on [Alpine]
• Cross-compiled builds are done using our (also auditable) [qemu]
• To fit build and complete make check test suite, BerkeleyDB is build separately [here]
• Each build produces binaries for: amd64, arm64v8, and arm32v7
• All architectures are aggregated under an easy-to-use [Docker Manifest]
• All [git-tags] are [build automatically], and with an [auditable trace]
• Each successful build of a git tag pushes result Docker image to Docker Hub⁠
• Images pushed to Docker Hub are never deleted (even if lnd version gets overridden, previous one is preserved)
• All final images are based on Alpine for minimum base size
• All binaries are [stripped]
• Each git-tag build is tagged with a unique tag number
• Each minor version is stored in a separate directory (for the ease of backporting patches)

⁠Troubleshooting

⁠Bitcoind isn't starting

Here are some possible reasons why.

⁠Permissions for the bitcoin data directory is not correct

The permissions for the bitcoin data direct is assumed to be UID 1000 (first user).

If you have a different setup, please do the following

# where ".bitcoin" is the data directory
sudo chown -R 1000.1000 $HOME/.bitcoin