ursuladurable streams
v0.10.1 · apache-2.0

Install

This page gets a single Ursula node running on your machine so you can try the API. There are two ways to do it:

PickWhen
DockerYou just want to try Ursula. One command, no toolchain.
Build from sourceYou want local binaries, plan to hack on Ursula, or can't run Docker.

Both start a single, non-replicated node on port 4437 that keeps nothing across restarts. The source build runs the in-memory engine. The Docker image runs a single Raft node whose WAL lives in a temporary directory inside the container. For a production cluster, see Deploy a Cluster.

Docker

Every release publishes a multi-arch image to GHCR:

docker run --rm -p 4437:4437 ghcr.io/tonbo-io/ursula:0.10.1

The image runs as a non-root user and contains both ursula (the server) and ursulactl (the operator CLI). A container that keeps its WAL on a volume (raft.wal.path), a node of a cluster or a single node, must list itself in [[raft.peers]] and set server.cluster_id in its configuration, the same on every node (see Configuration). Mount the WAL on a volume, never on the container's writable layer. Images are published only by the reviewed stable-release workflow, so pin the version you want to run.

Build from source

You need rustup, a C compiler, and pkg-config. The repository pins the toolchain in rust-toolchain.toml, so rustup selects the right nightly automatically.

Clone, build, and start the server:

git clone https://github.com/tonbo-io/ursula.git
cd ursula
cargo build --release -p ursula -p ursula-ctl
./target/release/ursula server

The server is now listening on 127.0.0.1:4437. The build also produces target/release/ursulactl, the operator CLI you will use once a cluster is up.

Verify

With the node running, from another terminal:

curl http://127.0.0.1:4437/__ursula/metrics

A JSON snapshot of runtime state means the node is up.

Next