Skip to main content
Version: Next

Deploy a node

A node is a managed service for pipelines and storage.

Install a node

Start at and click Add in the nodes pane. Then select your platform.


We provide Docker images and a Docker Compose file for a container setup. Install a node as follows:

  1. Enter a name for your node and click the download button to obtain the docker-compose.NODE.yaml configuration file where NODE is the name you entered for your node.
  2. Run
    docker compose -f docker-compose.NODE.yaml up

Edit the Docker Compose file and change environment variables to adjust the configuration.


We offer a native deployment on various Linux distributions. Install a node as follows:

  1. Enter a name for your node and click the download button to obtain a platform.yaml configuration file.
  2. Move the platform.yaml to <sysconfdir>/tenzir/plugin/platform.yaml so that the node can find it during startup where <sysconfdir> might be /etc. See the configuration files documentation for more options.
  3. Run our installer to install a binary package on any Linux distribution:
    curl | sh

The installer script asks for confirmation before performing the installation. If you prefer a manual installation you can also perform the installer steps yourself.

Download the latest Debian package and install it via dpkg:

dpkg -i tenzir-static-amd64-linux.deb


Please use Docker with Rosetta until we offer a native package.

Start a node

Implicit start with Docker

You can skip this step if you use Docker because docker compose up already starts a node for you.

Run the tenzir-node executable to start a node:

      _____ _____ _   _ ________ ____
|_ _| ____| \ | |__ /_ _| _ \
| | | _| | \| | / / | || |_) |
| | | |___| |\ |/ /_ | || _ <
|_| |_____|_| \_/____|___|_| \_\

Visit to get started.

This will spawn a blocking process that listens by default on the TCP endpoint Select a different endpoint via --endpoint, e.g., bind to an IPv6 address:

tenzir-node --endpoint=[::1]:42000

Stop a node

There exist two ways stop a server:

  1. Hit CTRL+C in the same TTY where you ran tenzir-node.
  2. Send the process a SIGINT or SIGTERM signal, e.g., via pkill -2 tenzir-node.

Sending the process a SIGTERM is the same as hitting CTRL+C.

Automate the deployment

Use systemd or Ansible to automate the deployment of a node.


The Tenzir package bundles a systemd service unit under <extraction_path>/lib/systemd/system/tenzir-node.service. The service is sandboxed and runs with limited privileges.

Prepare the host system

Please note that all subsequent commands require root privileges. The service requires a user and group called tenzir. You can create them as follows.

useradd --system --user-group tenzir

Once the user exists, you should create the directory for Tenzir's persistent data and change the permissions such that it is owned by the new tenzir user:

mkdir -p /var/lib/tenzir
chown -R tenzir:tenzir /var/lib/tenzir

Configure the unit

Locate the lines beginning with ExecStart= and ExecStop= at the bottom of the [Service] section in the unit file. Depending on your installation path you might need to change the location of the tenzir binary.

ExecStart=/path/to/tenzir start

In case your Tenzir deployment needs elevated privileges, e.g., to capture packets, you can provide them as follows:


Then link the unit file to your systemd search path:

systemctl link tenzir-node.service

To have the service start up automatically on system boot, enable it via systemd. Otherwise, just start it to run it immediately.

systemctl enable tenzir-node
systemctl start tenzir-node


The Ansible role for Tenzir allows for easy integration of Tenzir into existing Ansible setups. The role uses either the Tenzir Debian package or the tarball installation method depending on which is appropriate for the target environment. The role definition is in the ansible/roles/tenzir directory of the Tenzir repository. You need a local copy of this directory so you can use it in your playbook.


This example playbook shows how to run a Tenzir service on the machine example_tenzir_server:

- name: Deploy Tenzir
become: true
hosts: example_tenzir_server
remote_user: example_ansible_user
- role: tenzir
tenzir_config_dir: ./tenzir
tenzir_read_write_paths: [ /tmp ]
tenzir_archive: ./tenzir.tar.gz
tenzir_debian_package: ./tenzir.deb


tenzir_config_dir (required)

A path to directory containing a tenzir.yaml relative to the playbook.


A list of paths that Tenzir shall be granted access to in addition to its own state and log directories.


A tarball of Tenzir structured like those that can be downloaded from the GitHub Releases Page. This is used for target distributions that are not based on the apt package manager.


A Debian package (.deb). This package is used for Debian and Debian based Linux distributions.