Setting up a Bitcoin Development Environment and Test Network using Docker

Blockchain is a hot technology these days, and Bitcoin is the original implementation.  As a blockchain professional it is handy to be able to setup and run a Bitcoin network from scratch – checking out and compiling the code from Github, compiling and installing the code into a Docker container, and then running instances of the container to setup a small, local test network.

There are a number of projects you may want to explore (Bitcoin, Bitmessage, BigchainDB, Etherium, Hyperledger Fabric, etc.) and Docker allows you to setup multiple development environments without filling up your host with all the dependencies.

You can checkout the Bitcoin code from Github here, and I have setup a small project to build and run the Docker container here.  (Shoutout to Gerald and this blog post, which this project is based on.)

There are instructions to build and run the Bitcoin Docker image and test network in the Readme file in GitHub, so I won’t repeat everything here.  I’ll just explain a few things that aren’t covered in the readme.

The first step is to build a base Docker image that contains all the dependencies to compile and run Bitcoin – the Dockerfile is here.  It uses Ubuntu as a base image and adds all Bitcoin dependencies.

The second step is to run this base image and use it to compile the Bitcoin source.  The Bitcoin source is located on the host, and the directory is mounted in the Docker container using:

docker run ... -v $(BITCOIN_SRC):$(BITCOIN_SRC) -w $(BITCOIN_SRC) ...

(The location of the BITCOIN_SRC is configured in the Makefile, and you can edit this if you checkout your code in a different location.)

In the above, “-v” mounts the directory, and “-w” sets the current directory for running “make”.

Once the Bitcoin code is compiled and installed into the container, a second snapshot is saved using:

docker commit ...

… to save a new image.

Two instances of this image (“bob” and “alice”) are now started to run the local Bitcoin network:

docker run -d -it -p 18444:18444 -p 18332:18332 --name=alice --hostname=alice
docker run -d -it -p 19444:18444 -p 19332:18332 --name=bob --hostname=bob

Each image runs an instance of bitcoind, and the daemon is setup to run a local network (i.e. not connected to the Bitcoin production or test network):

bitcoind -regtest -daemon -printtoconsole

Commands can be invoked in each bitcoind process by executing bitcoin-cli in each Docker image:

# the following command is setup within the Makefile
docker exec alice bitcoin-cli -regtest $(bccmd)

# ... so to send a command to "alice" you simply run (for example to generate blocks):
make alice_cmd bccmd="generate 10"

It’s pretty simple!  If you have any questions please feel free to email me at