Run a Node with Docker

Stacks Blockchain with Docker

Run your own Stacks Blockchain node using docker-compose with just few commands using stacks-blockchain-docker


The minimum viable requirements are listed below.
While you can run a node using these specs, it's recommended to assign more than the minimum for better performance.
  • ⚠️ docker-compose version 2.2.2 or greater is required
  • 4GB memory
  • 1 Vcpu ( minimum of 2 Vcpu is recommended )
  • 250GB disk
MacOS with an ARM processor is NOT recommended
The way Docker for Mac on an Arm CPU is designed makes the I/O incredibly slow, and blockchains are very heavy on I/O. This only seems to affect MacOS, other Arm based systems like Raspberry Pi work as expected.


The <network> placeholder used below can be replaced with one of:
  • mainnet
  • testnet
  • mocknet
  1. 1.
    Clone the stacks-blockchain-docker repository locally
git clone && cd stacks-blockchain-docker
  1. 2.
    Start the Services
./ -n <network> -a start
With an optional HTTP proxy on port 80:
./ -n <network> -a start -f proxy

Accessing the services

For networks other than mocknet, downloading the initial headers can take several minutes. Until the headers are downloaded, the /v2/info endpoints won't return any data.
Follow the logs to track the sync progress:
./ -n <network> -a logs
  • Ports 20443-20444 are exposed on localhost
curl -sL localhost:20443/v2/info | jq -r
  • Port 3999 is exposed on localhost
curl -sL localhost:3999 | jq -r
  • Port 80 is exposed on localhost
curl -sL localhost/v2/info | jq -r
curl -sL localhost | jq -r


For schema-breaking upgrades to running instances of this repo, you'll need to run an event-replay.