Installation

Stream Trace ships as a single container image (git.prod.antomic.net/antomic/stream-trace) that serves both the API and the web UI on port 4000. It needs a reachable NATS cluster and a database - an embedded SQLite file by default, or PostgreSQL.

Private beta. Image pull access is provided to beta participants. Request access to receive registry credentials.

For the shortest supported path from the access email to a working evaluation, follow Start the self-serve beta.

Minimum requirements

• NATS with JetStream enabled, reachable from the container. Beta validation currently pins NATS 2.12.x; older 2.x releases may work but are not yet in the tested matrix.
• A database: nothing extra for SQLite (default), or PostgreSQL. Beta validation currently uses PostgreSQL 16.
• For any shared or production deployment: a JWT signing key (see Authentication).

Production Docker Compose

The beta release bundle includes deploy/compose/compose.yaml and a documented .env.example. It pins an immutable image, persists /data, binds to loopback, enables authentication, adds health checks and log rotation, and runs with a read-only root filesystem and dropped Linux capabilities.

cp deploy/compose/.env.example /secure/path/stream-trace.env
chmod 600 /secure/path/stream-trace.env
# Replace every placeholder, then:
docker compose -f deploy/compose/compose.yaml \
  --env-file /secure/path/stream-trace.env up -d

The service listens on 127.0.0.1:4000 by default. Put an HTTPS reverse proxy in front of it and keep ST_AUTH_COOKIE_SECURE=true; plain HTTP with secure cookies will not preserve login sessions. Use ST_AUTH_COOKIE_SECURE=false only for a loopback-only evaluation.

See Configuration for every setting, and Authentication for JWT keys, OIDC, and bootstrap options.

Kubernetes with Helm

The release bundle includes deploy/helm/stream-trace. The initial chart supports one combined api,indexer replica with a retained SQLite PVC, or combined replicas with an external PostgreSQL database. It does not claim a tested split-role HA topology.

kubectl create namespace stream-trace

kubectl --namespace stream-trace create secret docker-registry stream-trace-registry \
  --docker-server=git.prod.antomic.net \
  --docker-username="$STREAM_TRACE_REGISTRY_USERNAME" \
  --docker-password="$STREAM_TRACE_REGISTRY_PASSWORD"

JWT_SECRET="$(openssl rand -hex 32)"
kubectl --namespace stream-trace create secret generic stream-trace \
  --from-literal=ST_NATS_URL='nats://user:password@nats.example.com:4222' \
  --from-literal=ST_AUTH_JWT_ACTIVE_KEY_ID='beta-1' \
  --from-literal=ST_AUTH_JWT_KEYS="[{\"id\":\"beta-1\",\"secret\":\"${JWT_SECRET}\"}]"

helm upgrade --install stream-trace ./deploy/helm/stream-trace \
  --namespace stream-trace \
  --set-string image.tag=BETA_TAG \
  --set 'imagePullSecrets[0].name=stream-trace-registry' \
  --set-string streamTrace.existingSecret=stream-trace

The beta access email supplies the scoped registry credentials and immutable tag. Do not commit them, the NATS URL, or the generated JWT secret. The chart starts indexing disabled, retains the SQLite PVC after uninstall, and rejects multiple replicas with SQLite. See the chart README for PostgreSQL migrations, backup, and ingress TLS.