Purpose

This purpose of this project is to create docker images that can be used to run bdk regtest network tests locally and via github actions with a custom bitcoind version. The docker images are created for bitcoind and the original romanz/electrs electrum API server or the Blockstream/electrs electrum + esplora API server. The bitcoind docker image is built using a custom bitcoin repo and tag, as specified in the bitcoind/Dockerfile. The electrs and esplora docker images are built on top of the custom bitcoind image.

Github actions

Below are examples of how to use the images created by this project in github actions jobs:

electrum test job

 test-electrum:
     name: Test Electrum
     runs-on: ubuntu-16.04
     container: bitcoindevkit/electrs:<version>
     env:
       BDK_RPC_AUTH: COOKIEFILE
       BDK_RPC_COOKIEFILE: /root/.bitcoin/regtest/.cookie
       BDK_RPC_URL: 127.0.0.1:18443
       BDK_RPC_WALLET: bdk-test
       BDK_ELECTRUM_URL: tcp://127.0.0.1:60401
     ...

esplora test job

 test-esplora:
     name: Test Esplora
     runs-on: ubuntu-16.04
     container: bitcoindevkit/esplora:<version>
     env:
       BDK_RPC_AUTH: COOKIEFILE
       BDK_RPC_COOKIEFILE: /root/.bitcoin/regtest/.cookie
       BDK_RPC_URL: 127.0.0.1:18443
       BDK_RPC_WALLET: bdk-test
       BDK_ELECTRUM_URL: tcp://127.0.0.1:60401
       BDK_ESPLORA_URL: http://127.0.0.1:3002
     ...

Local bdk testing

Below is an example of how to run bdk electrum blockchain tests locally using the electrs docker image:

 # start the electrs docker container
 docker run -p 127.0.0.1:18443-18444:18443-18444/tcp -p 127.0.0.1:60401:60401/tcp --detach --rm --name electrs bitcoindevkit/electrs

 # confirm electrs is running
 docker logs electrs

 # get a copy of the bitcoind .cookie file
 # this needs to be done each time you run the container because the cookie file will change
 docker cp electrs:/root/.bitcoin/regtest/.cookie /tmp/regtest.cookie

 # in new shell from the `bdk` project repo directory run blockchains integration tests
 export BDK_RPC_AUTH=COOKIEFILE
 export BDK_RPC_COOKIEFILE=/tmp/regtest.cookie
 export BDK_RPC_URL=127.0.0.1:18443
 export BDK_RPC_WALLET=bdk-test
 export BDK_ELECTRUM_URL=tcp://127.0.0.1:60401
 
 cargo test --features electrum,test-blockchains --no-default-features electrum::bdk_blockchain_tests
 
 # kill the electrs container when you're done
 docker kill electrs

Below is an example of how to run bdk esplora blockchain tests locally using the esplora docker image:

 # start the esplora docker container
 docker run -p 127.0.0.1:18443-18444:18443-18444/tcp -p 127.0.0.1:60401:60401/tcp -p 127.0.0.1:3002:3002/tcp --detach --rm --name esplora bitcoindevkit/esplora

 # confirm esplora is running
 docker logs esplora
     
 # get a copy of the bitcoind .cookie file
 # this needs to be done each time you run the container because the cookie file will change
 docker cp esplora:/root/.bitcoin/regtest/.cookie /tmp/regtest.cookie

 # in new shell from the `bdk` project repo directory run blockchains integration tests
 export BDK_RPC_AUTH=COOKIEFILE
 export BDK_RPC_COOKIEFILE=/tmp/regtest.cookie
 export BDK_RPC_URL=127.0.0.1:18443
 export BDK_RPC_WALLET=bdk-test
 export BDK_ELECTRUM_URL=tcp://127.0.0.1:60401
 export BDK_ESPLORA_URL=http://127.0.0.1:3002
 
 cargo test --features esplora,test-blockchains --no-default-features esplora::bdk_blockchain_tests
 
 # kill the esplora container when you're done
 docker kill esplora

Local bdk-cli testing

Below is an example of how to test bdk-cli with electrum or esplora server APIs locally using the esplora docker image:

 # start esplora docker container
 docker run -p 127.0.0.1:18443-18444:18443-18444/tcp -p 127.0.0.1:60401:60401/tcp -p 127.0.0.1:3002:3002/tcp --detach --rm --name esplora bitcoindevkit/esplora
 
 # in a new shell sync wallet via the electrum APIs
 bdk-cli -n regtest wallet --server tcp://127.0.0.1:60401 --descriptor "wpkh(tpubEBr4i6yk5nf5DAaJpsi9N2pPYBeJ7fZ5Z9rmN4977iYLCGco1VyjB9tvvuvYtfZzjD5A8igzgw3HeWeeKFmanHYqksqZXYXGsw5zjnj7KM9/*)" sync     
 
 # or sync wallet via the esplora APIs
 bdk-cli -n regtest wallet --esplora http://127.0.0.1:3002 --descriptor "wpkh(tpubEBr4i6yk5nf5DAaJpsi9N2pPYBeJ7fZ5Z9rmN4977iYLCGco1VyjB9tvvuvYtfZzjD5A8igzgw3HeWeeKFmanHYqksqZXYXGsw5zjnj7KM9/*)" sync
 
 # kill the esplora container when you're done
 docker kill esplora   

Create aliases with the electrs container for local regtest electrum testing

alias elstart='docker run --detach --rm -p 127.0.0.1:18443-18444:18443-18444/tcp -p 127.0.0.1:60401:60401/tcp --name electrs bitcoindevkit/electrs'
alias elstop='docker kill electrs'
alias ellogs='docker container logs electrs'
alias elcli='docker exec -it electrs /root/bitcoin-cli -regtest -datadir=/root/.bitcoin $@'

Use aliases with the esplora container for local regtest electrum and esplora testing

alias esstart='docker run --detach --rm -p 127.0.0.1:18443-18444:18443-18444/tcp -p 127.0.0.1:60401:60401/tcp -p 127.0.0.1:3002:3002/tcp --name esplora bitcoindevkit/esplora'
alias esstop='docker kill esplora'
alias eslogs='docker container logs esplora'
alias escli='docker exec -it esplora /root/bitcoin-cli -regtest -datadir=/root/.bitcoin $@'

Use aliases to start an electrum container, view logs, run bitcoind cli commands, and stop the container

elstart  
ellogs  
elcli help    
elcli getwalletinfo    
elcli getnewaddress  
elstop  

Build local regtest bitcoind, electrs and esplora docker images and push to docker hub

These steps are only needed if you are a maintainer creating new versions of the published docker images for this project.

1. Login to docker hub

   docker login

2. Build and push new version of images, where is new git tag for this repo

   docker build -t bitcoindevkit/bitcoind:<version> bitcoind  
   docker build -t bitcoindevkit/electrs:<version> electrs
   docker build -t bitcoindevkit/esplora:<version> esplora
   
   docker push bitcoindevkit/bitcoind:<version>
   docker push bitcoindevkit/electrs:<version>
   docker push bitcoindevkit/esplora:<version>

3. Build and push latest image versions as needed

   docker build -t bitcoindevkit/bitcoind:latest bitcoind  
   docker build -t bitcoindevkit/electrs:latest electrs
   docker build -t bitcoindevkit/esplora:latest esplora
   
   docker push bitcoindevkit/bitcoind:latest
   docker push bitcoindevkit/electrs:latest
   docker push bitcoindevkit/esplora:latest