Installing Octez

Installing Octez#

In this how-to we explain how to get up-to-date binaries to run Tezos (more precisely, the “Octez” implementation of Tezos software) on any network (either on the mainnet or on one of the test networks). Octez consists of several binaries (i.e., executable files), including: a client, a node, and a baker.

There are several options for getting the binaries, depending on how you plan to use Octez:

  • installing packages. This is the easiest way to install native binaries for the latest stable release, together with their dependencies, using a package manager.

  • using docker images. This is the easiest way to run the latest stable release of the binaries in Docker containers, on any OS supported by Docker.

  • getting static binaries. This is the easiest way to get native binaries for the latest stable release, requiring no dependencies, under Linux.

  • using homebrew. For macOS (and also Linux) you can use our Homebrew formula to compile and install octez.

  • building the binaries via the OPAM source package manager. Take this way to install the latest stable release in your native OS environment, automatically built from sources.

  • Building Octez by compiling the sources like developers do. This is the way to take if you plan to contribute to the source code. It allows to install any version you want (typically, the current development version on the master branch) by compiling it yourself from the sources.

These different options are described in the following sections, except the last one, described in its own page.

Some Octez binaries also require certain parameter files to run. Only some of the packaged distributions include such parameter files. Therefore, depending on the type of installation and your user profile, you may have to install some extra parameter files separately. Their installation is described in page Building Octez from source, but those instructions may be used for other installation types:

Note that some of the packaged distributions are not only available for the latest stable release. For instance, static binaries are also available for release candidates, and Docker images are also available for the current development version (see Release System for more information).

When choosing between the installation options, you may take into account the convenience of the installation step (and of upgrading steps), but also efficiency and security considerations. For instance, static binaries have a different memory footprint compared to dynamically-linked binaries. Also, compiling the sources in the official Octez repository is more secure than installing OPAM packages from a repository that is not under Tezos control. In particular, compiling from sources enforces a fixed set of dependencies; when compiling via OPAM, this set of dependencies may change, which may or may not be compatible with your security practices.

All our installation scenarios are tested daily, including by automated means, to ensure that they are correct and up to date. These tests are performed by applying scenarios in several standard environments, from scratch. However, if you encounter problems when performing one of the installation scenarios in your own environment, you may want to take a look at Installation troubleshooting.

Installing binary packages#

When it comes to installing software, especially for critical applications like Tezos/Octez, it’s crucial to ensure a secure and stable environment. While compiling from source can provide customization options, it often introduces complexities and risks. Instead, opting for binary packages sucha as Deb or RPM packages from a trusted source simplifies installation and enhances security.

Deb or RPM packages compiled for a specific platform should be always preferred over statically compiled binaries. Deb or RPM packages can also be used to simplify the creation of OCI images or simply deployed on bare metal using provisioning tools such as Ansible.

Using the official Deb or RPM packages offers several advantages:

  • Security: Packages are pre-compiled and thoroughly tested, reducing the risk of vulnerabilities introduced during compilation. All our packages are signed and our supply chain is strictly monitored to make sure the packages that we deliver only use components that were vetted by our engineering team.

  • Stability: Packages from a trusted repository undergo rigorous testing, ensuring stability and compatibility with the target system. We make sure to compile our binaries in a clean environment and using an up-to-date software distribution. We use LTS (long-term service) distributions to enhance stability and reduce the attack surface.

  • Ease of Installation: Packages can be installed using standard package management tools, streamlining the process. For instance, apt is ubiquitous in the Debian world. These tools allow us to sign our packages that can be automatically verified by the end user during installation. We provide packages that allow the end user to easily tailor their installation for different use cases.

  • Reduced Downtime: With reliable binaries and straightforward installation, system downtime due to installation errors or compatibility issues is minimized. We carefully test the upgrade process of our packages to make sure that end users can enjoy a click and go upgrade process with near to zero downtime.

Ubuntu and Debian Octez packages#

If you’re using Ubuntu or Debian, you can install the Debian packages using apt directly from our APT repository.

We support the following distribution/releases:

  • debian/bookworm

  • ubuntu/noble

  • ubuntu/jammy

both on amd64 and arm64 architectures.

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

export distribution=debian
export release=bookworm

and run:

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

We also maintain a separate repository for release candidates. To install the last release candidate simply prepend RC/ to the distribution name as in export distribution=RC/debian

Then, to install the binaries, run the following command to install the octez-baker and all its dependencies:

sudo apt install octez-baker

Once the Octez binary packages are installed, they can be set up as services as explained in Setting up Octez Services.

To remove the Octez packages you can simply run the following command.

sudo apt-get autopurge -y octez-baker

If migrating from Serokell packages you can check out migration documentation Migrating from Serokell’s to Nomadic Labs’ packages.

To upgrade packages, use apt-get update and apt-get upgrade. If runnning Octez as services, see also how to restart them.

RPM Octez packages#

If you’re using Fedora or Rocky Linux, you can install RPM packages with Octez binaries from the Octez from our DNF repository. Currently we support the latest LTS release for Fedora and for RockyLinux :

  • rockylinux/9.3

  • fedora/39

  • fedora/42

both on amd64 and arm64 architectures.

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

export distribution=rockylinux
export release=9.3

and run:

  # Update and install the config-mananger plugin
  dnf -y update
  dnf -y install dnf-plugins-core

  # Add the repository
  dnf -y config-manager --add-repo "https://packages.nomadic-labs.com/$distribution/dists/$release/"
  # Install public key
  rpm --import "https://packages.nomadic-labs.com/$distribution/octez.asc"

For rockylinux user you also need to add the devel repository

dnf -y config-manager --set-enabled devel

To update the local dnf registry run:

dnf update

We also maintain a separate repository for release candidates. To install the last release candidate simply prepend RC/ to the distribution name as in export distribution=RC/rockylinux

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

dnf -y install octez-node
dnf -y install octez-client
dnf -y install octez-baker
dnf -y install octez-dal-node
dnf -y install octez-smart-rollup-node

To remove the Octez packages you can simply run the following command.

dnf -y remove octez-node octez-client octez-baker \
              octez-dal-node octez-smart-rollup-node

To upgrade packages, use dnf update. If runnning Octez as services, see also how to restart them.

Getting static binaries#

You can get static Linux binaries of the latest release from the Octez package registry.

This repository provides static binaries for x86_64 and arm64 architectures. Since these binaries are static, they can be used on any Linux distribution without any additional prerequisites. However, note that, by embedding all dependencies, static binary executables are typically much larger than dynamically-linked executables.

For upgrading to a newer release, you just have to download and run the new versions of the binaries.

Octez static binaries are signed via GPG. To verify that a binary was not tampered with, you can download and import our public GPG key and use gpg to verify the signature associated with the binary.

curl -O https://packages.nomadic-labs.com/octez.asc
gpg --import octez.asc
... # download the static binary you want to verify and the associated sig file
gpg --verify <bin>.sig <bin>

Using Homebrew#

On macOS and Linux, you can compile and install Octez using Homebrew. If Homebrew is not yet installed on your system, please refer to the official [Homebrew installation guide](https://brew.sh/) for detailed instructions.

Once Homebrew is set up, follow these steps to install Octez.

Download the Octez formula by executing the following command in your terminal:

curl -q "https://packages.nomadic-labs.com/homebrew/Formula/octez.rb" -O

For RC versions, do rather:

curl -q "https://packages.nomadic-labs.com/homebrew/RC/Formula/octez.rb" -O

Install Octez using the downloaded formula with the following command:

brew install -v ./octez.rb

Depending on the speed of your system, the build can take more than 10 minutes. We regularly test the build in our CI using macOS 14 (Sonoma) with Xcode 15 on an ARM-based Mac. More recent configurations should also work.

Using Docker images#

For every change committed in the GitLab repository, Docker images are automatically generated and published on DockerHub. This provides a convenient way to run an always up-to-date octez-node.

From version 22.0 all Octez Docker images are signed using Cosign. You can verify if the images are correctly signed, using Cosign.

You can use the Docker images either directly or using Docker compose files, as explained next. In both cases, you need to have Docker installed and started (Docker Desktop would suffice for the instructions below).

Plain Docker images#

The Docker images can be directly used to run the different Octez binaries. To make sure you use the most recent version of Octez, run:

docker pull tezos/tezos-bare:latest

For instance, to run a node on the Ghostnet test network, starting from a snapshot, in Rolling history mode, start with a fresh directory and configure the node:

mkdir $HOME/rolling-data-directory
docker run -it --rm \
  --volume "$HOME/rolling-data-directory:/home/tezos/.tezos-node" \
  tezos/tezos-bare:latest \
  octez-node config init --network ghostnet --rpc-addr 127.0.0.1 \
    --history-mode rolling

(You may use another location than $HOME, but note that option --volume requires absolute paths.)

Then, download and import a snapshot, and finally run the node:

wget -O $HOME/rolling <snapshot-url>
docker run -it --rm \
  --volume "$HOME/rolling-data-directory:/home/tezos/.tezos-node" \
  --volume "$HOME/rolling:/rolling:ro" \
  tezos/tezos-bare:latest \
  octez-node snapshot import /rolling
docker run --name octez-local-node -d \
  --volume "$HOME/rolling-data-directory:/home/tezos/.tezos-node" \
  tezos/tezos-bare:latest \
  octez-node run

You may check when your node is bootstrapped by executing in another terminal:

docker exec -it octez-local-node octez-client bootstrapped

You may stop and restart the node as needed, for instance if you need to upgrade the version of the storage:

docker stop octez-local-node
docker run --rm --volumes-from octez-local-node tezos/tezos-bare:latest \
  octez-node upgrade storage
docker start octez-local-node

Docker compose files#

Another way to run those Docker images is with docker-compose. docker-compose files are available for all active protocols in directory scripts/docker. Each compose file is able to launch services for a node, a baker, and an accuser for the given protocol.

First, you have to make some choices:

  • choose one of the above protocols and download its compose file

  • choose a network to connect to (a testnet name, sandbox, or mainnet); that network must currently run your protocol

  • choosing the desired history mode (rolling, full, or archive)

  • specify a vote for the liquidity baking feature (on, pass, or off)

For instance, to configure and run the node on the active protocol on Ghostnet, in Rolling history mode:

export PROTO=parisC
wget https://gitlab.com/tezos/tezos/-/raw/master/scripts/docker/$PROTO.yml
export LIQUIDITY_BAKING_VOTE=pass
docker compose -f $PROTO.yml run --rm -it \
  octez-node octez-node --network ghostnet --history-mode rolling

(Note in the command above that octez-node is the name of both the container and executable.)

Note

If the node complains that it is configured for another network, you’ll have to remove the node configuration file before running it:

docker compose -f $PROTO.yml run --rm \
  --entrypoint='sh -c "rm /var/run/tezos/node/data/config.json"' \
  octez-node

The node is now configured and started correctly, but may take a very long time to bootstrap. In most practical cases, you have to restart it from a snapshot file. For that, you have to stop the node by hitting ^C (or executing in another terminal docker compose -f $PROTO.yml stop octez-node), then clean up its data directory and import a snapshot that you previously downloaded:

docker compose -f $PROTO.yml run --rm \
  --entrypoint='sh -c "cd /var/run/tezos/node/data/; \
    rm -fr lock store context daily_logs"' \
  octez-node
wget -O $HOME/rolling <snapshot-url>
docker compose -f $PROTO.yml run --rm -it -v "$HOME/rolling:/snapshot:ro" \
  octez-node octez-snapshot-import

Now you can start all the services:

docker compose -f $PROTO.yml up

You may check when your node is bootstrapped by running octez-client inside the node’s container:

docker compose -f $PROTO.yml exec octez-node octez-client bootstrapped

You may stop and restart the node as needed. For instance if the Octez version you are using requires to upgrade the version of the storage, you can restart the node after upgrading the storage:

docker compose -f $PROTO.yml stop octez-node
docker compose -f $PROTO.yml run octez-node octez-upgrade-storage
docker compose -f $PROTO.yml up octez-node

Building Docker Images Locally#

The docker image used throughout the docker-compose files is fetched from upstream, but you can also build one locally and reference it. Run the following command to build the image:

./scripts/create_docker_image.sh

And then update the docker-compose file (e.g., alpha.yml) with the docker tag:

node:
  image: tezos:latest
  ...

Docker Image Configuration#

Lastly, the entrypoint script (scripts/docker/entrypoint.sh) provides the following configurable environment variables:

  • DATA_DIR: The directory to store the node’s data (defaults to /var/run/tezos).

  • NODE_HOST: The name of the node container (defaults to node).

  • NODE_RPC_PORT: The RPC port inside the container the node listens to (defaults to 8732).

  • NODE_RPC_ADDR: The RPC address inside the container the node binds to (defaults to [::]).

  • PROTOCOL: The protocol used.

These variables can be set in the docker-compose file, as demonstrated in scripts/docker/alpha.yml:

octez-node:
  ...
  environment:
    PROTOCOL: alpha
  ...

If the above options are not enough, you can always replace the default entrypoint and command fields.

version: "3"
services:
  octez-node:
    container_name: octez-node-alpha
    entrypoint: /bin/sh
    command: /etc/my-init-script.sh
    volumes:
      - ./my-init-script.sh:/etc/my-init-script.sh
      - ...
    environment:
      PROTOCOL: alpha
 ...

Installing binaries#

Depending on your operating system, you may install Octez (dynamically-linked) binaries and their dependencies by first downloading the packages for your distribution from the Octez release page, browsing to your distribution and then installing them with your package tool manager. Most of the configuration options are accessible by the user in /etc/default/<package>.

If you are upgrading from a different package distributor such as Serokell’s tezos-packaging, please pay attention to the possible differences between the two packages, in particular regarding the home directory for the tezos user.

There are several packages:

  • octez-client: the client for manipulating wallets and signing items

  • octez-node: the Octez node

  • octez-baker: the Octez baking and VDF daemons

  • octez-smartrollup: the Octez Smart Rollup daemons

  • octez-signer: the remote signer, to hold keys on (and sign from) a different machine from the baker or client

Building from sources via OPAM#

The easiest way to build the binaries from the source code is to use the OPAM source package manager for OCaml.

This is easier than setting up a complete development environment as described in Building Octez from source, like developers do. However, this method is recommended for expert users as it requires basic knowledge of the OPAM package manager and the OCaml packages workflow. In particular, upgrading Octez from release to release might require tinkering with different options of the OPAM package manager to adjust the local environment for the new dependencies.

Environment#

Currently Octez is being developed for Linux x86_64, mostly for Ubuntu and Fedora Linux. The following OSes are also reported to work: macOS (x86_64), Arch Linux ARM (aarch64), Debian Linux (x86_64). A Windows port is feasible and might be developed in the future.

Note

If you build the binaries by using the following instructions inside a Docker container, you have to give extended privileges to this container, by passing option --privileged to the docker run command.

Warning

Mixing LLVM and GNU binutils toolchains can cause issues when building Octez. If you encounter an error like this, it may be that you have tools from both LLVM and GNU in scope.

Error: ExternalToolError { reason: "Failed to create archive index with `ranlib`", tool: "ranlib", args: ["liboctez_rust_deps.a"], stdout: "", stderr: "LLVM ERROR: Invalid encoding\n" }

In this case, refer to Mixing LLVM and GNU binutils.

Install OPAM#

First, you need to install the OPAM package manager, at least version 2.1, that you can get by following the install instructions.

After the first install of OPAM, use opam init --bare to set it up while avoiding to compile an OCaml compiler now, as this will be done in the next step.

Install Octez OPAM packages#

The latest Octez release is available (as soon as possible after the release) directly as OPAM packages.

Note

Every file related to OPAM is (by default) in $HOME/.opam which means that, first, OPAM installs are user-specific and, second, you can get rid of everything by removing this directory (+ updating your rc files ($HOME/.bashrc, $HOME/.profile, $HOME/.zshrc, $HOME/.emacs, …) if you asked/allowed OPAM to add some lines in them).

The binaries need a specific version of the OCaml compiler (see the value of variable $ocaml_version in file scripts/version.sh). To get an environment with it do:

wget -O latest-release:version.sh https://gitlab.com/tezos/tezos/raw/latest-release/scripts/version.sh
source latest-release:version.sh
opam switch create for_tezos $ocaml_version
eval $(opam env)

Note

The opam switch create command may fail if the switch already exists; you are probably re-installing or upgrading an existing installation. If the required compiler version has not changed since the last time, you may simply ignore this error. Otherwise, you are upgrading to a new compiler, so look at the relevant section below.

The command eval $(opam env) sets up required environment variables. OPAM will suggest to add it in your rc file. If, at any point, you get an error like octez-something: command not found, first thing to try is to (re)run eval $(opam env --switch $ocaml_version) (replace $ocaml_version with its value in scripts/version.sh) to see if it fixes the problem.

Note

If an OPAM commands times out, you may allocate it more time for its computation by setting the OPAMSOLVERTIMEOUT environment variable (to a number of seconds), e.g. by adding OPAMSOLVERTIMEOUT=1200 before the command. If no timeout occurs, you may omit this part.

Now, install all the binaries by:

opam install octez

You can be more specific and only opam install octez-node, opam install octez-baker-alpha, …

Warning

Note that opam install octez-client and opam install octez-signer are “minimal” and do not install the support for Ledger Nano devices. To enable it, run opam install ledgerwallet-tezos in addition to installing the binaries. (The macro meta-package tezos installs ledgerwallet-tezos.)

Updating via OPAM#

Installation via OPAM is especially convenient for updating to newer versions. Once some libraries/binaries are installed and new versions released, you can update by:

opam update
opam upgrade

It is recommended to also run the command opam remove -a in order to remove the dependencies installed automatically and not needed anymore. Beware not uninstall too much though.

Identified situations where it will be more tricky are:

  • When the OCaml compiler version requirement changes. In this case, you have several possibilities:

    • Be explicit about the “upgrade” and do opam upgrade --unlock-base ocaml.$new_version tezos. Note that starting from OPAM version 2.1, this option is replaced by --update-invariant (see the opam-switch manual).

    • Remove the existing switch (e.g., opam switch remove for_tezos, but be aware that this will delete the previous installation), and replay the installation instructions.

    • Replay the installation instructions while creating a different switch (e.g. ocaml_${ocaml_version}_for_tezos), but be aware that each switch consumes a significant amount of disk space.

  • When there are Rust dependencies involved. The way to go is still unclear. The solution will be defined when delivering the first release with Rust dependencies.

Appendix#