Skip to main content

Installation & Set up

In this chapter, we will see the CLI command lines to install the necessary dependencies to run a Tezos node.

caution

The current Octez version is v20.2 and the protocol version is Paris.

Running an Octez node​

A node is responsible for receiving, validating and transmitting blocks and operations to nodes it is connected to on the network.

What you need​

Basic Node​

  • 2 CPU Cores
  • 8GB of RAM + 8GB of swap (or 16GB of RAM)
  • 100GB SSD storage (or similar I/O performance)
  • A low-latency reliable internet connection
caution

For a baking node, see the requirements here

Set up using Docker images​

In this part, we will see how to install Tezos with Docker.

Docker​

Step 1: Installation

If you don't have Docker on your machine, you can install it with the following command:

sudo apt install docker.io

and follow instructions on: https://docs.docker.com/engine/install/linux-postinstall/.

Step 2: Let's config and run!

Run the node in detached mode (-d), as instance on the testnet ParisCnet network with the history-mode "full" using the following command:

docker run --name=octez-public-node-full -v node-data-volume:/var/run/tezos/node tezos/tezos:latest octez-node --network=parisCnet

This command will automatically download the tezos/tezos:latest image:

  • -v node-data-volume:/var/run/tezos/node mount node-data-volume to the specified container. It is where blockchain data will be stored

  • --network= NETWORK selects which network to run. Possible values are: sandbox, mainnet, [testnet] (e.g. ghostnet, parisCnet. Learn more about testnet aliases here). Default is mainnet.

  • --history-mode= MODE lets you set the mode for the node's blockchain history storage. Possible values are archive , full (default), full:N , rolling , rolling:N.

    • Archive mode retains all data since the genesis block.

    • Full mode only maintains block headers and operations allowing replaying of the chain since the genesis if wanted. Full mode is recommended to bake. More information here.

    • Rolling mode retains only the most recent data and deletes the rest.

For both Full and Rolling modes, it is possible to adjust the number of cycles to preserve by using the :N annotation. The default number of preserved cycles is 5. The value experimental-rolling is deprecated but is equivalent to rolling which should be used instead.

Read more about node configuration here.

After a few minutes, your node identity will be generated and you will be able to check if the node is bootstrapped:

docker exec -it octez-public-node-full octez-client --endpoint http://127.0.0.1:8732 bootstrapped

(Use Ctrl+C to stop logs displaying)

Some useful commands

To see the manual of commands you can use:

docker run -it tezos/tezos:latest man

To see the various commands and options for the tezos node, use the following command:

docker run -it tezos/tezos:latest octez-node --help

To use the client:

docker exec -it octez-public-node-full octez-client --help

To see the logs : 

docker logs octez-public-node-full

Docker-compose​

One way to run those Docker images is with Docker Compose!

Step 1: Let's launch the node!

The code below launches a full node for the Paris protocol (mainnet). More information here.

version: "3.4"
volumes:
  node_data_full:
    name: mainnet-node
    external: false  
  client_data:
    name: mainnet-client
    external: false
services:
####################################################################################################################################
# You have to uncomment this section if you want to synchronize your node using a snapshot, else you can ignore or delete it.
# Replace /absolute/path/to/your_snapshot.full:/snapshot by the absolute path to the downloaded snapshot.
###################################################################################################################################  
#  import:
#    image: tezos/tezos:latest
#    container_name: octez-snapshot-import
#    command: octez-snapshot-import
#    volumes:
#      - node_data_full:/var/run/tezos/node
#      - client_data:/var/run/tezos/client
#      - "/absolute/path/to/your_snapshot.full:/snapshot"
################################################################################################
# If you want to run a node with history-mode=full, keep that "node_full" part, else delete it.
# You can change the version of the image of tezos in : image: tezos/tezos:v20.2
# You can change the --network=NETWORK option.
################################################################################################
  node_full:
    container_name: octez-public-node-full
    image: tezos/tezos:latest
    command: octez-node --net-addr :9732 --rpc-addr 127.0.0.1:8732 --rpc-addr 0.0.0.0:8732 --allow-all-rpc 0.0.0.0:8732 --history-mode=full
    ports:
    - '9732:9732'
    - '8732:8732'
    expose:
    - "8732"
    - "9732" 
    privileged: true
    volumes:
     - node_data_full:/var/run/tezos/node
     - client_data:/var/run/tezos/client
     - /dev/bus/usb:/dev/bus/usb
    restart: on-failure

Copy-paste the code above into a docker-compose.yml file, and start the node with:

docker-compose -f docker-compose.yml up -d

To check if the node is bootstrapped:

docker exec -it octez-public-node-full octez-client --endpoint http://127.0.0.1:8732 bootstrapped
Bonus: Quick synchronization from a snapshot

If you want your node to be bootstrapped quickly, you can synchronize it with the blockchain using a snapshot.

1. Download a .full snapshot from a snapshot provider (https://xtz-shots.io/, https://snapshots.tezos.marigold.dev/, https://snapshots-tezos.giganode.io/, https://lambsonacid.nl/), in your current repository by replacing with <snapshot_url> in following command:

wget <snapshot_url>

2. Launch the node daemon:

docker-compose up -d node_full
sudo docker exec -it octez-public-node-full sh
sudo rm /var/run/tezos/node/data/lock
exit

3. Stop the node:

docker-compose stop node_full

4. Execute these commands to clean up data and avoid duplicates:

sudo su
rm -rf /var/lib/docker/volumes/mainnet-node/_data/data/context
rm -rf /var/lib/docker/volumes/mainnet-node/_data/data/store
rm -rf /var/lib/docker/volumes/mainnet-node/_data/data/lock
rm -rf /var/lib/docker/volumes/mainnet-node/_data/data/daily_logs/

(do Ctrl+d to quit su mode)

5. In the .yml file presented in Step 1, replace /absolute/path/to/your_snapshot.full:/snapshot by the absolute path to the downloaded snapshot. You can use pwd command to know the absolute path of your current repository. ( Read the comment in the .yml file in Step 1 )

6. Upload the snapshot into the mainnet-node volume (You must uncomment the dedicated import part of the docker-compose file that was previously commented with #):

docker-compose up import

You will have to wait ~1-2 hours to import a full snapshot.

7. Start synchro from snapshot:

docker-compose stop import
docker-compose up -d node_full
Bonus: Upgrade your node storage

Some protocol or client changes require upgrading the node storage. You can simply update it with the following commands:

1. Stop the running container:

docker-compose stop node_full

2. Upgrade the storage:

docker run -it -v node_data_full:/var/run/tezos/node tezos/tezos:latest octez-upgrade-storage
danger

If you encounter an error, follow these steps before proceeding to step 2:

1. Go inside the container:

docker run -it --entrypoint=/bin/sh -v node_data_full:/var/run/tezos/node tezos/tezos:latest

2. Delete lock files and change node data file ownership/group:

cd /var/run/tezos/node/
sudo chown -R tezos.tezos .
rm data/lock

Set up using APT with Octez packages​

If you’re using Ubuntu or Debian, you can install the same packages as in the release page using apt directly from our APT repository, instead of going to the Octez release page as explained above.

We support the following distribution/releases: - debian/bookworm - ubuntu/noble - ubuntu/jammy

both on amd64 and arm64 architectures.

Step 1: Installation

In order to add the Tezos package repository to your machine, do:

export distribution=debian
export release=bookworm

and run:

  apt-get install -y sudo gpg curl

  curl "https://packages.nomadic-labs.com/$distribution/octez.asc" |
    sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/octez.gpg
  echo "deb [arch=amd64] https://packages.nomadic-labs.com/$distribution $release main" |
    sudo tee /etc/apt/sources.list.d/octez.list
  sudo apt-get update

Then, to install the binaries, run the following commands:

sudo apt-get install -y octez-client
sudo apt-get install -y octez-node
sudo apt-get install -y octez-baker
Step 2: Let's config and run!

The following command configures the node for the Ghostnet Network (Tezos semi-permanent test network) and stores data in the specified directory ~/tezos-ghostnet with the full mode:

octez-node config init --data-dir ~/tezos-ghostnet --network=ghostnet --history-mode=full

  • data-dir Define the directory where the data will be stored (by default, it is in .octez-node).

  • --network=NETWORK Select which network to run. Possible values are: sandbox, mainnet, [testnet] (e.g. ghostnet, parisCnet. Learn more about testnet aliases here). Default is mainnet.

  • --history-mode=MODE Set the mode for the chain's data history storage. Possible values are archive , full (default), full:N, rolling, rolling:N.

    • Archive mode retains all data since the genesis block.

    • Full mode only maintains block headers and operations allowing replaying of the chain since the genesis if wanted. Full mode is recommended to bake. More information here.

    • Rolling mode retains only the most recent data and deletes the rest.

For both Full and Rolling modes, it is possible to adjust the number of cycles to preserve by using the :N annotation. The default number of preserved cycles is 5. The value experimental-rolling is deprecated but is equivalent to rolling which should be used instead.

Read more about node configuration here.

You can run the node with:

octez-node run --rpc-addr 127.0.0.1:8732 --log-output tezos.log --data-dir ~/tezos-ghostnet

  • --rpc-addr url:port activate the RPC interface that will allow communication with the node. By default, it runs on port 8732 so it is not mandatory to specify it.

  • --log-output tezos.log will saved logs of the node in the tezos.log file.

  • data-dir Define the directory where the data will be stored (by default, it is in .octez-node).

Step 3: Check synchronization ✅

The Octez client can be used to interact with the node. It can query its status or ask the node to perform some actions. For example, after starting your node, you can check if it has finished synchronizing with the following command (you can use another terminal window if you still watch the log):

octez-client -E http://127.0.0.1:8732/ bootstrapped
  • -E option is equal to --endpoint option

When you see the message " Node is Bootstrapped ", your Tezos node is synchronized with the blockchain and you may now perform operations on it!

Bonus: Quick synchronization from a snapshot

If you want your node to be bootstrapped quickly, you can synchronize it with the blockchain using a snapshot.

1. Download a .full snapshot from a snapshot provider (https://xtz-shots.io/, https://snapshots.tezos.marigold.dev/, https://snapshots-tezos.giganode.io/, https://lambsonacid.nl/) in your current repository by replacing with <snapshot_url> in following command:

wget <snapshot_url>

2. Register the current directory in a variable:

path=$(pwd)

3. Import from the snapshot!

(Replace <name_of_snapshot_file>)

octez-node snapshot import $path/<name_of_snapshot_file>

(It is possible to define the directory where the data will be stored with --data-dir directory, by default, it is in .octez-node)

4. You can get some information with the following command:

octez-node snapshot info $path/<name_of_snapshot_file>
Bonus: Video tutorial with Github codespaces

To help you if you have any doubts about what to do in one of these steps or what is expected to happen when you run the commands, you may check this video that shows the different steps. Some long parts of waiting for commands to terminate have been cut, in practice, the execution took around 20 minutes.

Set up by building from source​

In this part, we will see how to install Tezos from source. The easiest way to build the binaries from the source code is to use the OPAM source package manager for OCaml.

This method is recommended for advanced users as it requires basic knowledge of the OPAM package manager and the OCaml packages workflow. In particular, upgrading Tezos from release to release might require tinkering with different options of the OPAM package manager to adjust the local environment for the new dependencies.

From scratch method​

Step 1: Install OPAM

First, you need to install the OPAM package manager, at least version 2.0, that you can get by following the install instructions. The quickest way to get the latest opam up and working is to run this script:

bash -c "sh <(curl -fsSL https://raw.githubusercontent.com/ocaml/opam/master/shell/install.sh)"
note

If you have trouble with curl, just download the script and run sh install.sh.

For the next command line, answers the prompts with 'N' then 'y'. You may also be prompted for your sudo password. You may encounter a "switch" error, but you can ignore it.

opam init --bare
Step 2: Install Rust
Compiling Tezos requires the Rust compiler, version 1.52.1, and the Cargo package manager for Rust to be installed. If you have [rustup](https://rustup.rs/) installed, you can use [rustup](https://rustup.rs/) to install both. If you do not have `rustup`, please avoid installing it from Snapcraft; you can rather follow the simple installation process shown below:
cd $HOME
wget https://sh.rustup.rs/rustup-init.sh
chmod +x rustup-init.sh
./rustup-init.sh --profile minimal --default-toolchain 1.52.1 -y

Once Rust is installed, note that your PATH environment variable (in .profile) may be updated and you will need to restart your session so that changes can be taken into account. Alternatively, you can do it manually without restarting your session with the following command :

source $HOME/.cargo/env
Step 3: Install Tezos dependencies

Install the libraries that Tezos is dependent on:

sudo apt-get install -y rsync git m4 build-essential patch unzip wget pkg-config libgmp-dev libev-dev libhidapi-dev opam jq zlib1g-dev bc autoconf

Get the source code:

git clone https://gitlab.com/tezos/tezos.git
cd tezos
git checkout latest-release

Install tezos dependencies:

make build-deps

You may encounter a "switch" error, but you can ignore it.

You may encounter failures in the processes of the make build-deps command. In that case, just re-type the command opam init --bare to re-initiate.

Step 4: Compile sources

Compile sources:

eval $(opam env)
make
Step 5: Check installation

To check the installation you can use the following commands:

octez-node --version
Step 6: Let's config and run!

It is possible to define the directory where the data will be stored with --data-dir (by default, it is in .octez-node).

--network=NETWORK Select which network to run. Possible values are: sandbox, mainnet, [testnet] (e.g., ghostnet, parisCnet. Learn more about testnet aliases here). Default is mainnet.

--history-mode= MODE Set the mode for the chain's data history storage. Possible values are archive , full (default), full:N, rolling, rolling:N.

  • Archive mode retains all data since the genesis block.
  • Full mode only maintains block headers and operations allowing replaying the chain since the genesis if wanted (full mode is recommended to bake. More information here).
  • Rolling mode retains only the most recent data and deletes the rest.

For both Full and Rolling modes, it is possible to adjust the number of cycles to preserve by using the :N annotation. The default number of preserved cycles is 5. The value experimental-rolling is deprecated but is equivalent to rolling which should be used instead.

Read more about node configuration here).

For example, the following command configures the node for the Ghostnet Network and stores data in the specified directory ~/tezos-ghostnet with the full mode.

octez-node config init --data-dir ~/tezos-ghostnet --network=ghostnet --history-mode=full

You can run the node with :

octez-node run --data-dir ~/tezos-ghostnet --rpc-addr 127.0.0.1:8732 --log-output tezos.log

The parameter --rpc-addr url:port activate the RPC interface that will allow communication with the node. By default, it runs on port 8732 so it is not mandatory to specify it. The file tezos.log will be saved in /home/user/.

Step 7: Check synchronization ✅

The Octez client can be used to interact with the node. It can query its status or ask the node to perform some actions. For example, after starting your node, you can check if it has finished synchronizing with the following command (you can use another terminal window if you still watch the log) :

octez-client -E http://127.0.0.1:8732/ bootstrapped

Where:

  • -E option is equal to --endpoint option

When you see the message " Node is Bootstrapped ", your Tezos node is synchronized with the blockchain, and you may now perform operations on it!

Tezos OPAM packages method​

Step 1: Install OPAM

First, you need to install the OPAM package manager, at least version 2.0, that you can get by following the install instructions. The quickest way to get the latest opam up and working is to run this script:

bash -c "sh <(curl -fsSL https://raw.githubusercontent.com/ocaml/opam/master/shell/install.sh)"
note

If you have trouble with curl, just download the script and run sh install.sh.

For the next command line, answers the prompts with 'N' then 'y'. You may also be prompted for your sudo password. You may encounter a "switch" error, but you can ignore it.

opam init --bare
Step 2: Get an environment
wget -O latest-release:version.sh https://gitlab.com/tezos/tezos/raw/latest-release/scripts/version.sh

The binaries need a specific version of the OCaml compiler (see the value of the variable $ocaml_version in file /tezos/scripts/version.sh).

source latest-release:version.sh
opam switch create for_tezos $ocaml_version
eval $(opam env)

If you get a c compiler error, run this to install some necessary tools:

sudo apt-get install build-essential
Step 3: Get dependencies

In order to get the system dependencies of the binaries, do:

opam depext octez
Step 4: Install binaries
opam install octez
Bonus: Quick synchronization from a snapshot

If you want your node to be bootstrapped quickly, you can synchronize it with the blockchain using a snapshot.

1: Download a .full snapshot from a snapshot provider (https://xtz-shots.io/, https://snapshots.tezos.marigold.dev/, https://snapshots-tezos.giganode.io/, https://lambsonacid.nl/) in your current repository by replacing with <snapshot_url> in following command:

wget <snapshot_url>

2: Register the current directory in a variable:

path=$(pwd)

3: Import from the snapshot!

(Replace <name_of_snapshot_file>)

octez-node snapshot import $path/name_of_snapshot_file

(It is possible to define the directory where the data will be stored with --data-dir directory, by default, it is in .octez-node)

4: You can get some information with the following command:

octez-node snapshot info $path/name_of_snapshot_file

This module is a prerequisite to becoming a baker, and the Deploy Bakers module explains how to become a baker and start earning Tez rewards.

References​

[1] https://tezos.gitlab.io/introduction/howtoget.html