How to run a Tezos Node with Docker

5 min readJul 18, 2019

‌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 fronted 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:

https://hub.docker.com/r/tezos/tezos

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 https://get.docker.com | 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

If this command succeeds, you have installed docker correctly, to make things easier here is a video of the entire process:

Sart 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:

Start a Tezos Container like a Pro

In this section we will look at 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.

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" }  }

Here are three common options we can set in the config:

History Mode

Tezos supports 3 different history modes, these affect the amount of storage needed by your node and how much information is available in the RPC API.

These mores are:

full
stores all data since the beginning of the chain but removes archived data
rolling
most lightweight, only stores data since the last snapshot.
archive
stores everything, requires a lot of Storage space

You can set the mode in the config like this:

{ “shell”: {“history_mode”: “full”} }

Bootstrap Peers

Here you can specify the inital peers your node will connect to,
specify them like this:

{ “p2p”: {“bootstrap-peers”: [ip1:port1, ip2:port2,…]} }

Private Mode

In private mode your node will not connect to nodes other than your bootstrap peers, Bakers often do this to hide their IP and only connect to one ”Frontend Node” that is hosted somewhere else, enable it with:

{ “p2p”: {“private-mode”: true } }

You can view all possible config options with this command:

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

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"services:  
  mainnet:
    image: tezos/tezos:mainnet
    command: ["tezos-node"]
    hostname: node
    ports:
      - "8732:8732"
      - "9732:9732/udp"
    volumes: 
       - "/data/tezos:/var/run/tezos/node"
    deploy:   
      resources:
        limits:
          cpus: '1'
          memory: 4096M
      restart_policy:
        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 1 CPU 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 https://github.com/stefanprodan/swarmprom, so lets git clone this project…

$ git clone https://github.com/stefanprodan/swarmprom.git
$ cd swarmprom

…create a run.sh file with the following content…

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

..and start the monitoring setup:

$ chmod +x run.sh
$ ./run.sh

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:

Final Notes

We now have a running Tezos Node + Monitoring System, there is a lot more to get into that are beyond the scope of this Guide and depend on your Use-Case, for example, Grafana can be set up to send you Slack notifications in case your nodes throws an error, Or if you run this on a public server you should not expose your RPC port to the world like we did in this Guide, to do this change the port section in the docker-compose to:

ports:
      - mode: host
        target: 8732
        published: 8732

For more information on all RPC calls I recommend looking at the official documentation here:https://tezos.gitlab.io/tezos/api/rpc.html

And for all other questions I recommend you join us in our matrix/riot chat on https://tzchat.org/ :)