Deploy a node

Deploying a node means spinning it up in one of the supported runtimes. The primary choice is between a containerized with Docker or a native deployment with our static binary that runs on amd64 and arm64 architectures.

Docker

We recommend using Docker to deploy a Tenzir node, as it’s the easiest way to get started.

After provisioning a node, proceed as follows:

1. Select the Docker tab 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 --detach

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

Stop a node

Stop a node via the down command:

docker compose -f docker-compose.NODE.yaml down

Stop a node and delete its persistent state by adding --volumes:

docker compose -f docker-compose.NODE.yaml down --volumes

Update a node

Run the following commands to update a Docker Compose deployment with a configuration file docker-compose.NODE.yaml:

docker compose -f docker-compose.NODE.yaml pull
docker compose -f docker-compose.NODE.yaml down
docker compose -f docker-compose.NODE.yaml up --detach

Note that we pull first so that the subsequent downtime between down and up is minimal.

Linux

We offer a static binary package on various Linux distributions.

Install a node

Second, choose the Linux tab and proceed as follows:

1. Provision the node and download its config.
2. Create a directory for the platform configuration.

   mkdir -p /opt/tenzir/etc/tenzir/plugin

3. Move the downloaded platform.yaml configuration file to the directory so that the node can find it during startup:

   mv platform.yaml /opt/tenzir/etc/tenzir/plugin

4. Run the installer and follow the instructions to download and start the node:

   curl https://get.tenzir.app | 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. See the configuration files documentation for details on how the node loads config files at startup.

Debian

Download the latest Debian package and install it via dpkg:

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

You can uninstall the Tenzir package via apt-get remove tenzir. Use purge instead of remove if you also want to delete the state directory and leave no trace.

RPM-based (RedHat, OpenSUSE, Fedora)

Download the latest RPM package and install it via rpm:

rpm -i tenzir-static-amd64-linux.rpm

Nix

Use our flake.nix to run an ad-hoc tenzir pipeline:

nix run github:tenzir/tenzir/latest

Or run a node without installing:

nix shell github:tenzir/tenzir/latest -c tenzir-node

Install a Tenzir Node by adding github:tenzir/tenzir/latest to your flake inputs, or use your preferred method to include third-party modules on classic NixOS.

Pre-built only!

The default attributes of the flake contain some closed source plugins and will fail to download locally. The flake is only for public consumption together with the Tenzir cachix cache.

Any

Download a tarball with our static binary for all Linux distributions and unpack it into /opt/tenzir:

tar xzf tenzir-static-x86_64-linux.tar.gz -C /

We also offer prebuilt statically linked binaries for every Git commit to the main branch.

curl -O https://storage.googleapis.com/tenzir-dist-public/packages/main/tarball/tenzir-static-main.gz

Start a node manually

The installer script uses the package manager of your Linux distribution to install the Tenzir package. This typically also creates a systemd unit and starts the node automatically.

For testing, development, our troubleshooting, run the tenzir-node executable to start a node manually:

tenzir-node

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

          v4.0.0-rc6-0-gf193b51f1f
Visit https://app.tenzir.com to get started.

[16:50:26.741] node listens for node-to-node connections on tcp://127.0.0.1:5158
[16:50:26.982] node connected to platform via wss://ws.tenzir.app:443/production

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.

Hitting CTRL+C is equivalent to manually sending a SIGTERM signal.

AWS

The recommended way to run a Tenzir node in AWS is with Elastic Container Service (ECS).

This guide walks through manual setup of a single Tenzir node.

Prerequisites

Before you begin, you’ll need a valid TENZIR_TOKEN. You can obtain this by provisioning a node and downloading the Docker Compose configuration file.

1. Go to AWS Marketplace and subscribe to the free Tenzir Node product.

   

2. Accept the terms to subscribe to the offering.

   

3. Navigate to Amazon Elastic Container Service (ECS).

   

4. Create a new cluster. Choose between EC2 or Fargate based on your needs:

   • EC2 clusters give you full control over the underlying instances. They’re ideal for long-running workloads with consistent resource requirements.
   • Fargate clusters provide serverless container execution where you pay only for the resources you use. They’re cost-effective for workloads with variable demand.

   

5. Create a task definition to specify how the Tenzir node container should run.

   

   In the Containers section, enter the repository URL from your AWS Marketplace subscription:

   709825985650.dkr.ecr.us-east-1.amazonaws.com/tenzir/tenzir-node:v5.9.0

   Each node version has its own image tag. The example above uses version 5.9.0. Check the node changelog for the latest version.

6. Return to your cluster, navigate to the Tasks tab, and click Run new task. Select the task definition you just created.

   

   In the Container overrides section, add the TENZIR_TOKEN environment variable with the token value from the prerequisites.

   

   Click Create to launch your node.

7. Once the container starts successfully, your node will automatically connect to your workspace.

Azure

To run a node in Azure, we recommend using Azure Container Instances (ACI), which allows you to run Docker containers without having to setup VMs.

Azure Container Instances (ACI)

Prior to getting started, you need a valid TENZIR_TOKEN that you can obtain after provisioning a node and downloading the Docker Compose configuration file.

Create a new container instance

1. Open https://portal.azure.com/.
2. Navigate to the Container instances.
3. Click the Create button.

Basics

In the Basics tab, perform the following action:

1. Choose a container name.
2. For Image source, select Other registry.
3. For Image, enter tenzir/tenzir-node.

Networking

In the Networking tab, configure the ports you plan to use for pipelines that receive incoming connections.

Advanced

In the Advanced tab, enter the TENZIR_TOKEN environment variable from your Docker Compose file.

Create

Once you’ve completed the configuration, click the Create button. Your node is now up and running.

macOS

Looking for a native macOS package? We’re not quite there yet—but you can still run Tenzir smoothly on macOS using Docker.

Want to see a native macOS build? Let us know! Drop your vote in our Discord community—we prioritize what our users need most.

Tenzir does run well on macOS under the hood. Docker just bridges the gap for now.

Ansible

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.

Example

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
  roles:
    - role: tenzir
      vars:
        tenzir_config_dir: ./tenzir
        tenzir_read_write_paths: [/tmp]
        tenzir_archive: ./tenzir.tar.gz
        tenzir_debian_package: ./tenzir.deb

Variables

tenzir_config_dir (required)

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

tenzir_read_write_paths

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

tenzir_archive

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.

tenzir_debian_package

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