Practical overview
When it fits
Use it when you want to run a self-hosted Bitcoin node through Docker and need the documented container configuration and image-building options.
Who it is for
- Operators self-hosting a fully validating Bitcoin node.
- Administrators who want to configure Bitcoin Core through container environment variables or a mounted bitcoin.conf.
- Builders who need an image based on a selected Bitcoin release or Git object.
Documented uses
- Run bitcoind in a Docker container with a mounted data directory.
- Generate node configuration from environment variables or supply a custom configuration file.
- Set RPC credentials, port and bind behavior, testnet mode, transaction indexing, wallet disablement and selected ZeroMQ settings.
- Build a node image from a release or arbitrary Git object.
Requirements & limits
The README requires Docker on the host. It describes using a registry image or building an image locally.
- The README says Bitcoin Core binaries are retrieved from bitcoincore.org and integrity-verified.
- Registry image references are mutable; the project recommends using a content hash or building images yourself.
- The example keeps RPC mapped to localhost. Remote RPC access requires changing the host port mapping and setting BTC_RPCBIND=0.0.0.0.
- The default container user is documented as UID and GID 1000; rebuild arguments allow specifying different IDs.
- The Dockerfile implementation may change even though the README says the container interface is intended to remain stable; pin the repository to a Git hash if relying on implementation particulars.
Check current requirements in the official documentation. Source-based guidance does not mean OpenViST has run or independently tested this project.
Start a node with generated configuration
Run the documented Docker image with a persistent data directory and generated Bitcoin configuration.
Before you start
- Docker installed on the host
- A host directory for Bitcoin data
- An environment file containing BTC_RPCPASSWORD
Steps
Create a directory on the host for Bitcoin data and prepare an environment file with the RPC password.
Run the documented image with BTC_RPCUSER and BTC_TXINDEX environment settings, the environment file, and a mount to /bitcoin/data.
Publish port 8333 and map RPC port 8332 to 127.0.0.1; follow the container output with docker logs -f bitcoind.
Expected outcome
A Docker container starts with generated configuration, persistent data storage and RPC bound to the host's loopback address.
Guide limitations
- The example uses image tag 0.20.1.
- The README warns that entering the RPC password directly in a command may expose it in shell history.
- The documented command starts the container; it does not specify a time or completion criterion for initial node synchronization.
Build an image from a selected Git object
Build a Docker image using a chosen Bitcoin Git ref or object.
Before you start
- Docker installed on the host
- A local clone of the docker-bitcoind repository
Steps
Clone the repository and change into its directory.
Run ./bin/build-docker-bitcoin with a Git ref or object, such as master or v24.0rc2.
Expected outcome
The documented build script is invoked for the selected Git object.
Guide limitations
- The README does not specify further build or runtime verification steps for this recipe.
Sources & review
Source record details
- Source availability
- Active
- Sources checked
- 18 October 2026
- Original website title
- jamesob/docker-bitcoind · Official homepage title · retained in its source language