Quickstart

This quickstart builds Ursa from source and runs the Docker Compose stack the project itself uses for local development: Pulsar, running on Ursa storage in place of BookKeeper, against Oxia and a local S3-compatible store.

1. Prerequisites

• Java 17+
• Maven 3.6.3+
• Docker and Docker Compose
• A GitHub personal access token with read:packages scope — Ursa's dependencies, including streamnative-bom and pulsar-bom, are published to GitHub Packages rather than Maven Central

Add the token to ~/.m2/settings.xml:

<servers>
  <server>
    <id>github</id>
    <username>YOUR-GITHUB-ACCOUNT</username>
    <password>YOUR-GITHUB-TOKEN</password>
  </server>
</servers>

2. Clone and build

git clone https://github.com/ursaio/ursa-storage.git
cd ursa-storage
mvn clean install -DskipTests

This builds every module in the project — from lakestream-api down to ursa-storage-compact — and installs them to your local Maven repository. Skipping tests keeps the first build quick. To exercise the test suite instead of just compiling, mvn test runs unit tests, mvn verify adds integration tests, and mvn test -pl ursa-storage-core scopes either to a single module.

3. Start the local infrastructure

The repo's Docker Compose file brings up the three services a local Pulsar-on-Ursa deployment needs:

docker compose -f docker/docker-compose.yaml up -d

Once the stack is up, the Pulsar service is reachable at pulsar://localhost:6650 and its HTTP API at http://localhost:8080.

4. Use Ursa

With the library built, there are two directions to take it:

• Embed it directly. Add lakestream-api and ursa-storage-lakestream as dependencies and call StreamCatalog, Log, and LogCursor from your own JVM code. Ursa's artifacts publish under the io.streamnative groupId — Ursa for Kafka currently pins them at 4.1.3.2 — but they aren't published to Maven Central, so building from source, as above, is the dependable path today. See Java clients for the interfaces and setup.
• Run a full Kafka-compatible cluster. Ursa for Kafka is the fastest way to see a diskless, leaderless cluster end to end — it wraps this same storage engine behind the Kafka protocol.

What's next

• Architecture for how the modules built above map onto the Lakestream pattern.
• Feature matrix for what's supported today.
• Ursa for Kafka quickstart for a complete cluster running in Docker.