Run a Node with Docker

Stacks Blockchain with Docker

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

Requirements

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

• 8GB memory if running only a Stacks node

• 16 GB memory if running Stacks + Bitcoin node

• 1 Vcpu ( minimum of 2 Vcpu is recommended )

• 500GB disk for Stacks node

• 1TB disk space for Bitcoin node

MacOS with an ARM (M-series chip) 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 with the M-series chip, other Arm based systems like Raspberry Pi work as expected.

Storage

A fully synced Stacks node can use significant disk space and will continue to grow. If your boot drive doesn't have enough room, mount a dedicated disk and symlink the persistent-data directory before starting the node:

Point persistent-data to an external disk

# If persistent-data already exists, move its contents first
mv persistent-data/mainnet /mnt/stacks-data/mainnet
rmdir persistent-data

# Create the symlink
ln -s /mnt/stacks-data persistent-data

The Docker volumes write to persistent-data/mainnet/, so the symlink redirects all chainstate, database, and event data to the external disk transparently.

Quickstart

The <network> placeholder used below can be replaced with one of:

• mainnet

• testnet

• mocknet

1

Clone the repository

Clone the stacks-blockchain-docker repository locally and change into the directory:

Clone repository

git clone https://github.com/stacks-network/stacks-blockchain-docker && cd stacks-blockchain-docker

2

Start the services

Start the docker-compose services for the chosen network:

Start services

./manage.sh -n <network> -a start

macOS users: The manage.sh script uses GNU sed syntax that is incompatible with macOS BSD sed. If you encounter sed: bad flag in substitute command errors, install GNU sed and prepend it to your PATH:

brew install gnu-sed
PATH="/opt/homebrew/opt/gnu-sed/libexec/gnubin:$PATH" ./manage.sh -n <network> -a start

With an optional HTTP proxy on port 80:

Start with proxy

./manage.sh -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:

Follow logs

./manage.sh -n <network> -a logs

stacks-blockchain:

• Ports 20443-20444 are exposed on localhost

Check stacks-blockchain /v2/info

curl -sL localhost:20443/v2/info | jq -r

stacks-blockchain-api:

• Port 3999 is exposed on localhost

Check stacks-blockchain-api

curl -sL localhost:3999 | jq -r

proxy:

• Port 80 is exposed on localhost

Check proxy

curl -sL localhost/v2/info | jq -r
curl -sL localhost | jq -r

Upgrades

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