🌊 Welcome to Riptide

Give people who love working with networks the tools they deserve to optimize and troubleshoot network traffic.

📖 Documentation: https://riptide.space/docs/

👩‍🏭 Build from source

Requirements:

• git
• Java 25
• Docker with Docker Compose

git clone https://github.com/Riptide-Labs/riptide.git && cd riptide

Compile from source with tests

make

Build a container image in your local registry

make oci

Render a test coverage report (JaCoCo)

make coverage

Run the integration and e2e test tier (requires Docker; drives real NetFlow v5/v9 and IPFIX traffic from the nl6 simulator through riptide into ClickHouse). The nl6 image tag is pinned in src/test/java/org/riptide/e2e/Nl6Container.java and is bumped deliberately — it is a wire-format contract, not a Dependabot-managed dependency.

make e2e

The e2e tier includes an optional full mode (Linux only): nl6 devices export flows from per-device source IPs and riptide's SNMP enrichment walks back to each device's simulated agent. It is gated on RIPTIDE_E2E_FULL_MODE=1 and skipped otherwise (e.g. on macOS). To run it on a Linux host:

docker network create --subnet 172.30.42.0/24 nl6-fullmode
sudo ip route add 10.42.0.0/16 via 172.30.42.10
sudo sysctl -w net.ipv4.conf.all.rp_filter=2
sudo sysctl -w net.ipv4.conf.default.rp_filter=2
RIPTIDE_E2E_FULL_MODE=1 make e2e

🕹️ Run on your local system

cd target
java -jar riptide-flows-*.jar

🕹️ Run with Docker Compose

git clone https://github.com/Riptide-Labs/riptide.git

Run the published image ghcr.io/riptide-labs/riptide:latest with ClickHouse and Grafana

cd deployment/riptide
docker compose up -d

• Grafana: http://localhost:3000 with login admin/admin. Set GF_SECURITY_ADMIN_PASSWORD before starting to use your own password.
• ClickHouse on 127.0.0.1:8123 with login default/riptide. Set CLICKHOUSE_PASSWORD to use your own; the whole stack follows it.
• Send flows to your Riptide server on 9999/udp

Tip

To run the image you built with make oci (riptide:local) instead, add the dev override: docker compose -f compose.yml -f compose.override.dev.yml up -d.

Run just a ClickHouse stack

cd deployment/clickhouse
docker compose up -d

👩‍🔧 Configuration

The default configuration is shipped in application.properties. Override it in one of two places:

1. The file /etc/riptide/config.yaml, loaded when present. In the container, mount your file at that path.
2. Environment variables: upper case, dots and dashes become underscores.

riptide.clickhouse.endpoint -> RIPTIDE_CLICKHOUSE_ENDPOINT

Details, including what cannot be set through the environment, are in the Plain JAR page.

📦 Make a release

git checkout main && git pull
git checkout -B release
git push -u origin release
make release RELEASE_VERSION=1.0.0

Pushing the resulting vX.Y.Z tag is what publishes the release: signed jar, DEB and RPM packages, an SBOM and a multi-arch container image on ghcr.io/riptide-labs/riptide. The full procedure, the image tagging scheme and the cosign verify commands are in RELEASING.md.

👋 Say hello

You are very welcome to join us to make this project a better place. You can find us at:

• Riptide Chat
• Riptide Meetup Calendar

👮 Contribution Guidelines

Start with CONTRIBUTING.md. In short: work from an issue, Conventional Commits, sign off every commit with git commit -s, and label AI-assisted work with an Assisted-by: trailer.

Found a security problem? Please don't open an issue — see SECURITY.md.

📜 License

Riptide is licensed under the GNU General Public License v3.0 or later (GPL-3.0-or-later). See LICENSE for the full text.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Dustin Frisch 💻 🔬 👀 🤔

Ronny Trommer 💻 📖 🚇 🚧

mvrueden 💻 👀

Christian Pape 💻

This project follows the all-contributors specification. Contributions of any kind welcome!