Deploy with DEB / RPM packages

Every GitHub release ships architecture-independent .deb and .rpm packages (one package serves amd64 and arm64). They install the jar, a hardened systemd service, and a configuration skeleton — Java 25 is resolved automatically from your distro or JDK-vendor repositories.

Install

Debian / Ubuntu (Debian 13+, Ubuntu 22.04+):

curl -LO https://github.com/Riptide-Labs/riptide/releases/download/v0.13.1/riptide_0.13.1_all.deb
sudo apt install ./riptide_0.13.1_all.deb

apt pulls openjdk-25-jre-headless from the distro archive if no Java 25 is present; an already installed Temurin, Corretto, or Zulu 25 also satisfies the dependency.

RHEL / Rocky / Alma (9.7+, 10.1+) and Fedora (43+) — dnf installs directly from the URL:

sudo dnf install https://github.com/Riptide-Labs/riptide/releases/download/v0.13.1/riptide-0.13.1-1.noarch.rpm

dnf pulls java-25-openjdk-headless from AppStream; Temurin and Zulu 25 also satisfy the dependency.

Amazon Corretto on RPM systems

Corretto's rpm does not provide the jre-25-headless virtual the package depends on. If Corretto is your runtime, install the package with rpm -i --nodeps and manage the Java requirement yourself — or let dnf install java-25-openjdk-headless alongside.

What the package installs

Path	Purpose
/usr/share/riptide/riptide.jar	the engine
/usr/lib/systemd/system/riptide.service	sandboxed unit, runs as the riptide system user
/etc/riptide/config.yaml	configuration (root:riptide 0640 — may hold credentials)
/etc/riptide/riptide.env	JVM options and environment variables for the service

Configure ClickHouse access

Installation is deliberately passive: nothing starts until Riptide can reach a ClickHouse. Edit /etc/riptide/config.yaml (installed root:riptide 0640, so it may hold credentials) and point it at your database over the HTTP interface (port 8123):

riptide:
  clickhouse:
    endpoint: http://clickhouse.example.com:8123
    database: riptide
    username: default
    # password: left unset = the default user's empty password

By default Riptide manages its own schema (manage-schema: true), creating the database and the flows table on first start — no manual DDL needed (the configured user needs CREATE rights).

For a password-protected user, prefer a secret reference over an inline literal so no plaintext lives in the file:

riptide:
  clickhouse:
    endpoint: http://clickhouse.example.com:8123
    database: riptide
    username: riptide
    password: vault://secret/riptide/clickhouse#password   # or env://, file://, sops://

A ClickHouse credential that cannot be resolved is fatal at startup (unlike SNMP, which degrades). See ClickHouse configuration for schema ownership, multi-tenant write isolation, and the identity columns.

Enable and start

Define at least one receiver in the same file (everything from the configuration chapters goes there), then start the service:

sudo systemctl enable --now riptide
journalctl -u riptide -f

File-based configuration hot-reloads. riptide.env takes JAVA_OPTS and environment-variable configuration; changes there need a systemctl restart riptide.

Upgrades

Install the newer package the same way, then restart the service — the running JVM keeps executing the old jar until you do:

sudo systemctl restart riptide

Your edited /etc/riptide files are preserved by default: rpm writes new defaults as .rpmnew next to them; dpkg keeps your version unless the packaged default changed too, in which case it asks (unattended upgrades can pass -o Dpkg::Options::=--force-confold to always keep yours).

Receivers on privileged ports

The unit runs unprivileged; the conventional receiver ports (IPFIX 4739, NetFlow v9 2055, sFlow 6343) need no special rights. To bind a port below 1024, add a drop-in:

sudo systemctl edit riptide

[Service]
AmbientCapabilities=CAP_NET_BIND_SERVICE