🧪 Bitcoin Lab (in Docker)

A fully self-contained Bitcoin Core environment running in regtest mode (by default) using Docker — great for testing, learning, and scripting.

✅ Features

• 🐳 Runs in Docker (no need to install Bitcoin Core natively)
• 🔐 Verifies GPG signatures and SHA256 checksums
• ⚙️ Preconfigured for regtest (server, txindex, fallbackfee, RPC creds) but you can add your own ./.bitcoin/bitcoin.conf file.
• 💾 Blockchain state is persisted locally in .bitcoin/
• 🏁 Ready to use bitcoin-cli right after starting

🚀 Getting Started

# 1. Clone and navigate to the project
git clone https://github.com/nseguias/bitcoin-lab-docker.git && cd bitcoin-lab-docker

# 2. Build the image
docker build --platform linux/x86_64 -t bitcoin-lab-ready .

# 3. Start the container with persistent regtest data
./run-bitcoin-lab.sh

Then inside the container, run:

bitcoin-cli getblockchaininfo

You should see something like this:

{
  "chain": "regtest",
  "blocks": 0,
  "headers": 0,
  "bestblockhash": "0f9188f13cb7b2c71f2a335e3a4fc328bf5beb436012afca590b1a11466e2206",
  "bits": "207fffff",
  "target": "7fffff0000000000000000000000000000000000000000000000000000000000",
  "difficulty": 4.656542373906925E-10,
  "time": 1296688602,
  "mediantime": 1296688602,
  "verificationprogress": 1,
  "initialblockdownload": true,
  "chainwork": "0000000000000000000000000000000000000000000000000000000000000002",
  "size_on_disk": 293,
  "pruned": false,
  "warnings": []
}

📄 Configuration

The container uses ./.bitcoin/bitcoin.conf on your host. If it doesn't exist, it's created automatically with:

regtest=1
fallbackfee=0.0001
server=1
txindex=1
rpcuser=satoshi
rpcpassword=satoshi

I recommend changing rpcuser and rpcpassword for something else but it's not strictly necessary.

You can also change regtest=1 for testnet, signet, or mainnet with its desired configuration.

🧼 Resetting the Node

NOTE: by resetting the node you will remove previous blockchain data, wallets, etc. so make sure you back them up if you think you'll need it later.

To clear all data and start fresh run:

rm -rf .bitcoin
./run-bitcoin-lab.sh

📂 File Structure

docker/
├── bitcoin-lab.sh         # Setup script (downloads + verifies Bitcoin Core)
├── Dockerfile             # Docker config
├── run-bitcoin-lab.sh     # Helper script to run container
├── .bitcoin/              # Your regtest data and bitcoin.conf
└── README.md

🛠️ Notes

• Ports are not exposed by default. Add -p flags if needed.
• bitcoind runs as a daemon automatically in the container.
• No wallets are created by default. Use createwallet via RPC if needed.

---

MIT License