Installation

Runs as a single streamstack binary. The server holds metadata locally (SQLite) or in Postgres and stores feed data in an S3-compatible bucket, and exposes HTTP APIs. The same binary also drives the CLI against a running server.

Prerequisites

Requirement	Notes
JDK 21	Gradle toolchains fetch JDK when one is not installed
S3 bucket	Holds wal-segments, packs, manifests, and commit records under feeds/
AWS credentials	Default SDK chain: environment variables, shared profile, or instance role

Or use SSO profile, after aws sso login. The dist and harness modules have SSO SDK modules.

Build

From the repository root:

./gradlew :dist:installDist

That installs dist/build/install/streamstack/bin/streamstack. The repo-root ./streamstack shim runs that binary and builds it on first use:

./streamstack serve --bucket my-bucket --region us-east-1

Run Server

Single-node deployments use a local SQLite metadata file. Feed data still lives in the bucket.

./streamstack serve --bucket my-bucket --region us-east-1

Flag	Purpose
--bucket	S3 bucket name (required)
--region	AWS region (defaults to the SDK region chain)
--endpoint	S3 endpoint override for MinIO or other compatible stores
--metadata	SQLite metadata file path (default streamstack.db)
--metadata-url	JDBC URL for shared metadata (jdbc:postgresql://... only)
--port	HTTP listen port (default 8080)
--lease-ttl	Writer lease TTL in seconds (default 30)
--node-id	Stable node identity for lease ownership
--advertise-url	Base URL other nodes use to reach this server

When --metadata-url is set, Postgres credentials come from STREAMSTACK_DB_USER and STREAMSTACK_DB_PASSWORD.

CLI

Client sub-commands attach to the running server. The default base URL is http://localhost:8080. Point at another host or port with --url before the subcommand:

./streamstack feed create orders
./streamstack append orders --record k1=hello
./streamstack read orders --mode RAW

Subcommands include feed, append, read, subscribe, and admin for compaction, retention, export, resume, discard, and repair.

S3-Compatible Store

Pass --endpoint on serve (and on the harness) for MinIO or other path-style endpoints. StreamStack forces path-style access when an endpoint override is set.

./streamstack serve --bucket my-bucket \
  --endpoint http://127.0.0.1:9000

Metadata

SQLite metadata is a disk cache for leases, the commit index, subscriptions, and node registry. Deleting the file does not remove bucket data. On restart the server rebuilds metadata from the bucket (crash safe).

Postgres metadata is required when more than one server process shares write-path coordination. Object data remains in S3. Set --metadata-url and export database credentials:

docker run --name streamstack-pg -e POSTGRES_PASSWORD=streamstack \
  -e POSTGRES_USER=streamstack -e POSTGRES_DB=streamstack \
  -p 5432:5432 -d postgres:16-alpine

export STREAMSTACK_DB_USER=streamstack
export STREAMSTACK_DB_PASSWORD=streamstack

Multi Node

Run two processes against the same bucket and Postgres URL. Each node needs a distinct --node-id, --port, and --advertise-url:

./streamstack serve --bucket my-bucket --region us-east-1 \
  --metadata-url jdbc:postgresql://localhost:5432/streamstack \
  --node-id node-a --advertise-url http://127.0.0.1:8080 --port 8080

./streamstack serve --bucket my-bucket --region us-east-1 \
  --metadata-url jdbc:postgresql://localhost:5432/streamstack \
  --node-id node-b --advertise-url http://127.0.0.1:8081 --port 8081

Write-path requests that hit a non-owner are proxied to the live lease holder. Sealed reads work on any node. Subscription long-poll wakeups are node-local (for now), so cross-node long-poll falls back to timeout and re-read.

After install, run the harness matrix in Quickstart to verify bucket access and a local build.