Skip to main content

Docker Private Network

We provide a tool at tools/docker-network with which a local test network can be set up locally with docker.

Docker network

How to Use the Tool​

In the docker network run for example

./run.sh 5 1 1

The command ./run.sh spins up a GoShimmer network within Docker as schematically shown in the figure above. The first integer input defines the number of peer_replicas N. The second argument is optional for activating the Grafana dashboard, where

  • default (no argument) or 0: Grafana disabled
  • 1: Grafana enabled

More details on how to set up the dashboard can be found here.

The peers can communicate freely within the Docker network while the analysis and visualizer dashboard, as well as the peer_master's dashboard and web API are reachable from the host system on the respective ports.

The settings for the different containers (peer_master, peer_replica) can be modified in docker-compose.yml.

How to Use as Development Tool​

Using a standalone throwaway Docker network can be really helpful as a development tool.

Prerequisites:

  • Docker 17.12.0+
  • Docker compose: file format 3.5

Reachable from the host system

  • peer_master's analysis dashboard (autopeering visualizer): http://localhost:9000
  • peer_master's web API: http: http://localhost:8080
  • faucet's dashboard: http: http://localhost:8081

It is therefore possible to send blocks to the local network via the peer_master. Log blocks of a specific containter can be followed via

docker logs --follow CONTAINERNAME

Snapshot Tool​

A snapshot tool is provided in the tools folder. The snapshot file that is created must be moved into the integration-tests/assets folder. There, rename and replace the existing bin file (7R1itJx5hVuo9w9hjg5cwKFmek4HMSoBDgJZN8hKGxih.bin). After restarting the docker network the snapshot file will be loaded.

Docker Compose uses the SNAPSHOT_FILE environment variable to determine the location of the snapshot. Once you have a new snapshot you can simply set SNAPSHOT_FILE to the location of your new snapshot and Docker Compose will use your snapshot the next time you run docker compose up.

How to Use Block Approval Check Tool​

get_approval_csv.sh script helps you conveniently trigger the block approval checks on all nodes in the docker network, and gather their results in the csv folder.

Once the network is up and running, execute the script:

./get_approval_csv.sh

Example output:

Triggering approval analysis on peer_master and 20 replicas...
Triggering approval analysis on peer_master and 20 replicas... DONE
Copying csv files from peer_master and 20 replicas...
Copying csv files from peer_master and 20 replicas... DONE
Copied files are located at ./csv

The exported csv files are timestamped to the date of request.

csv
├── 210120_16_34_14-docker-network_peer_replica_10.csv
├── 210120_16_34_14-docker-network_peer_replica_11.csv
├── 210120_16_34_14-docker-network_peer_replica_12.csv
...

Note, that the record length of the files might differ, since the approval check execution time of the nodes might differ.

Spammer Tool​

The Spammer tool lets you add blocks to the tangle when running GoShimmer in a Docker network. In order to start the spammer, you need to send GET requests to a /spammer API endpoint with the following parameters:

  • cmd - one of two possible values: start and stop.
  • unit - Either mps or mpm. Only applicable when cmd=start.
  • rate - Rate in integer. Only applicable when cmd=start.
  • imif - (optional) parameter indicating time interval between issued blocks. Possible values:
    • poisson - emit blocks modeled with Poisson point process, whose time intervals are exponential variables with mean 1/rate
    • uniform - issues blocks at constant rate

Example requests:

http://localhost:8080/spammer?cmd=start&rate=10&unit=mps

http://localhost:8080/spammer?cmd=start&rate=10&unit=mps&imif=uniform
http://localhost:8080/spammer?cmd=stop

Tangle Width​

When running GoShimmer locally in a Docker network, the network delay is so small that only 1 tip will be available most of the time. In order to artificially create a tangle structure with multiple tips you can add a blockLayer.tangleWidth property to config.docker.json that specifies the number of tips that nodes should retain. This setting exists only for local testing purposes and should not be used in a distributed testnet.

Here is an example config that can be added:

{
  "blockLayer": {
    "tangleWidth": 10
  }
}

Running With docker compose Directly​

To get an instance up and running on your machine make sure you have Docker Compose installed.

Then you just need to run this command:

docker compose build
docker compose --profile grafana up -d

Note: Docker will build the GoShimmer image which can take several minutes.

Base Components​

These services that are created by default with docker compose up -d.

Configuration​

  • SNAPSHOT_FILE: The full path to the block snapshot file. Defaults to ./goshimmer/assets/7R1itJx5hVuo9w9hjg5cwKFmek4HMSoBDgJZN8hKGxih.bin
  • GOSHIMMER_TAG: (Optional) The iotaledger/goshimmer tag to use. Defaults to develop.
  • GOSHIMMER_CONFIG: The location of the GoShimmer config file. Defaults to ./config.docker.json.

Example​

You can set the environment variable configuration inline as seen in this example.

GOSHIMMER_TAG=develop docker compose up -d

Peer master​

A node that is used to expose ports via the host and to have a single attachment point for monitoring tools.

Volumes​

Docker Compose creates a mainnetdb volume to maintain a tangle even after tearing down the containers. Run docker compose down -v to clear the volume.

Ports​

The following ports are exposed on the host to allow for interacting with the Tangle.

PortService
8080/tcpWeb API
9000/tcpAnalysis dashboard

Peer replicas​

A node that can be replicated to add more nodes to your local tangle.

Ports​

These expose 0 ports because they are replicas and the host system cannot map a port to multiple containers.

Faucet​

A node that can dispense tokens.

Ports​

The following ports are exposed on the host to allow for interacting with the Tangle.

PortService
8081/tcpDashboard

Optional Components​

These services can be added to your deployment through --profile flags and can be configured with ENVIRONMENT_VARIABLES.

Grafana + Prometheus​

A set of containers to enable dashboards and monitoring.

Profile​

In order to enable these containers you must set the --profile grafana flag when running docker compose.

Configuration​
  • PROMETHEUS_CONFIG: Location of the prometheus config yaml file. Defaults to ./prometheus.yml.
Example​

You can set the environment variable configuration inline as seen in this example.

docker compose --profile grafana up -d
Ports​

The following ports are exposed on the host to allow for interacting with the Tangle.

PortService
3000/tcpGrafana
9090/tcpPrometheus