Local development

Set up and run a mocknet with docker


This guide helps you understand how to set up and run a mocknet for local development with Docker.



  1. Clone the repo locally:
git clone https://github.com/blockstack/stacks-local-dev ./stacks-local-dev && cd ./stacks-local-dev git clone https://github.com/blockstack/stacks-local-dev ./stacks-local-dev && cd ./stacks-local-dev
  1. Copy sample.env to .env:
cp sample.env .env cp sample.env .env
  1. Start the Mocknet:
./manage.sh mocknet up./manage.sh mocknet up
  1. Stop the Mocknet:
./manage.sh mocknet down./manage.sh mocknet down

Env Vars

All variables used in the .env file can be modified, but generally most of them should be left as-is.

Locally opened ports

In this section of the .env file, the values can be modified to change the ports opened locally by docker.

Currently, default port values are used - but if you have a running service on any of the defined ports, they can be adjusted to any locally available port.



Can be adjusted to:


Docker will still use the default ports internally - this modification will only affect how the host OS accesses the services.

For example, to access postgres (using the new port 5433) after running ./manage.sh mocknet up:

export PGPASSWORD='postgres' && psql --host localhost -p 5433 -U postgres -d stacks_node_apiexport PGPASSWORD='postgres' && psql --host localhost -p 5433 -U postgres -d stacks_node_api

System Resources

All sections in the .env file have specific CPU/MEM values, and can be adjusted to work in your local enviroment.

The variables take the form of xxxx_CPU and xxxx_MEM.




Mocknet does not require any settings for bitcoin


Default password is easy to guess, and we do open a port to postgres locally.

This password is defined in the file ./postgres/stacks-node-api.sql

If you update this value to something other than postgres, you'll have to adjust the value in the .env file as well, as the mocknet API uses this:


Running a local mocknet

Install/Update docker-compose

First, check if you have docker-compose installed locally:

docker-compose --version docker-compose version 1.27.4, build 40524192docker-compose --versiondocker-compose version 1.27.4, build 40524192

If the command is not found, or the version is < 1.27.4, run the following to install the latest to /usr/local/bin/docker-compose:

VERSION=$(curl --silent https://api.github.com/repos/docker/compose/releases/latest | jq .name -r) DESTINATION=/usr/local/bin/docker-compose sudo curl -L https://github.com/docker/compose/releases/download/${VERSION}/docker-compose-$(uname -s)-$(uname -m) -o $DESTINATION sudo chmod 755 $DESTINATIONVERSION=$(curl --silent https://api.github.com/repos/docker/compose/releases/latest | jq .name -r)DESTINATION=/usr/local/bin/docker-composesudo curl -L https://github.com/docker/compose/releases/download/${VERSION}/docker-compose-$(uname -s)-$(uname -m) -o $DESTINATIONsudo chmod 755 $DESTINATION

Ensure all images are up to date

You can run the following at anytime to ensure the local images are up to date:

./manage.sh mocknet pull./manage.sh mocknet pull

Services Running in Mocknet

Mocknet service names:

  • follower
  • api
  • postgres

Docker container names:

  • mocknet_stacks-node-follower
  • mocknet_stacks-node-api
  • mocknet_postgres

Starting Mocknet Services

Start all services:

```bash ./manage.sh mocknet up ``````bash./manage.sh mocknet up```

Stopping Mocknet Services

Stop all services:

```bash ./manage.sh mocknet down ``````bash./manage.sh mocknet down```

Or restart:

```bash ./manage.sh mocknet restart ``````bash./manage.sh mocknet restart```

Retrieving Mocknet logs

Tail logs with docker-compose:

```bash ./manage.sh mocknet logs ``````bash./manage.sh mocknet logs```

Accessing the services


  • Ports 20443-20444 are only exposed to the mocknet docker network.


  • Ports 3700, 3999 are exposed to localhost
curl localhost:3999/v2/info | jqcurl localhost:3999/v2/info | jq


  • Port 5432 is exposed to localhost (PGPASSWORD is defined in .env)
export PGPASSWORD='postgres' && psql --host localhost -p 5432 -U postgres -d stacks_node_apiexport PGPASSWORD='postgres' && psql --host localhost -p 5432 -U postgres -d stacks_node_api

Potential issues

Port already in use

If you have a port conflict, typically this means you already have a process using that same port.

To resolve, find the port you have in use (for example, 5432 and edit the .env file to use the new port)

netstat -anl | grep 5432 tcp46 0 0 *.5432 *.* LISTENnetstat -anl | grep 5432tcp46 0 0 *.5432 *.* LISTEN

Containers not starting

Occasionally, docker can get stuck and not allow new containers to start. If this happens, simply restart your docker daemon and try again.

BNS username not found

The mocknet is launched without the import of Stacks 1.0 name, only the test genesis chain state is imported. To change that comment out the corresponding line in stacks-node-follower/Config.toml.template like this:

# use_test_genesis_chainstate = true# use_test_genesis_chainstate = true

panic on launch

Verify that the path of the config file is correct in the .env file, in particular on Windows OS the slash (/) in path names can cause errors.

Stacks CLI
Technical Specifications
Powered by