Docker and Docker Swarm

‌In this Guide, we will look at how to run a Tezos Node with Docker on Linux, this Guide is primarily meant for people who want to run a public node to use the RPC API, or as a baking frontend node, or similar.

Docker is a platform that allows users to run applications as “Containers” without the need to compile Source Code, you simply download a ready-made container image and start it, the same Container Image can run on many different operating systems, so there is no need to manually deal with OS-specific dependencies and libraries, this is by far the easiest way to run a tezos node.

Official docker images for tezos are premade and can be found here:​

In the “Tags” section of this website, you will find all current versions of Tezos, we will have a look at this later, let’s make sure you have a running Docker setup first

Install Docker on Linux

Installing Docker on any modern Linux Distribution is quite easy, all we need to do is open a terminal and type this command:

$ curl | bash

After this we have to make sure your current user is allowed to execute docker commands, we can do that with:

$ usermod -aG docker $USER

For this change to take effect you will have to log out and log in again, after that you are able to create a test docker container with:

$ docker run hello-world

Here is a Video of the entire Process:

Tezos Running

Start a Tezos Container

At this point we can start a tezos node with one single command:

$ docker run --rm -it tezos/tezos:mainnet tezos-node

This is just a test to see that everything works, this will tell docker to download the official tezos image from dockerhub and run the tezos-node command inside the docker container.

The command uses two special flags, the first one is –rm, this flag tells Docker to delete the container after it has exited, we usually don’t want this but for a testing container, this is ok.

The second flag is -it, which makes sure docker attaches the container to your open terminal, later when we want to run docker in the background we have to omit this.

After some time your tezos node will have found enough connections to other nodes and start syncing blocks, if it does not start immediately have patience, it should look like this:

Tezos Running

Start a Tezos Container like a Pro

In this section we will look at many different Options and Settings we can tweak when running a Tezos Node with Docker, and also install Prometheus and Grafana, a comprehensive Monitoring System.

First, we will need to enable “Swarm Mode” of our docker installation. Swarm Mode allows docker to do many awesome things like Load-balancing across multiple machines, we will not take advantage of many of those great features in this Guide, we just use it because it makes our life a lot easier, so let’s enable docker swarm:

$ docker swarm init

This will generate Output about how to add other machines for more complicated setups, we will ignore this for the sake of simplicity.

We are gonna need a location where the tezos node will store its data, so let’s create a directory for that:

$ sudo mkdir /data  && sudo mkdir /data/tezos

and set permissions for that folder:

$ sudo chown $USER /data/tezos

Tezos Configuration

In the above directory, we will create a config.json file that holds all configuration options for tezos, a minimal config.json looks like this:

{ "p2p": {"listen-addr": "[::]:9732" }  }

Docker Container Configuration

We will save our docker setup in a file so we can keep track of the configuration, so create a docker-compose.yml file with the following content:

version: "3"

    image: tezos/tezos:mainnet
    command: ["tezos-node"]
    hostname: node
      - "8732:8732"
      - "9732:9732/udp"
      - "/data/tezos:/var/run/tezos/node"
          cpus: '2'
          memory: 4096M
        condition: on-failure
        delay: 5s
        max_attempts: 10   

In this file we define:

  • what image to use
  • what the start command is
  • what ports we want to have available ( RPC Port and P2P port )
  • where to store the tezos data
  • the maximum resource limits to 2 CPUs and 4096 MB Ram
  • and how to restart the node if it fails

Now we can deploy our setup with:

$ docker stack deploy -c docker-compose.yml tezos

and can check if the node is running with either docker ps or docker service ls, and we can see the node logs with

$ docker service logs tezos_mainnet -f

While we wait for our Node to start syncing Blocks, lets setup our Monitoring System.

Docker Monitoring

For this we will use the Grafana + Prometheus Stack from, so lets git clone this project…

$ git clone
$ cd swarmprom

…create a file with the following content…

ADMIN_USER=admin \
docker stack deploy -c docker-compose.yml mon

..and start the montoring setup:

$ chmod +x
$ ./

Wait a minute for everything to download and start, then open your browser and access your monitoring dashboard at http://localhost:3000, it should look like this: