Deploying

This directory contains the Compose stack used for local development and self-hosting, plus a first Helm chart for Kubernetes.

• Compose — compose/docker-compose.yml (release images) with compose/docker-compose.dev.yml layered on for hot-reload development. The root README.md quickstart and ../docs/onboarding.md walk through bringing it up with just dev.
• Helm — helm/nexus for a single-node Kubernetes deployment.

For image verification before you run anything, see ../docs/ops/releases.md. Operator deployment automation (image bundling, hardened server stack, backup/restore scripts) is host-provisioning tooling and lives outside this repository.

Operator responsibilities

The stack in this repository does not manage TLS, public exposure, or secret material for you:

• TLS is operator-supplied. The Compose stack serves plain HTTP on localhost; put your own TLS-terminating reverse proxy in front of anything publicly reachable.
• Ports: the stock Compose stack publishes the gateway (14450), several service health/debug ports, the console (14449), MinIO (9000/9001), Grafana (14470), and the OTel collector’s self-metrics (18888) to the host. Postgres, ClickHouse, NATS, and Valkey stay inside the compose network. See ../docs/reference/ports.md for the full table before exposing a host to a network you do not trust.
• Secrets: the committed defaults are development-only. For anything beyond a laptop, change every secret (NEXUS_SERVICE_TOKEN, AUTH_JWT_SECRET, the *_PASSWORD values, S3 keys) and render .env from a real secret manager. See ../docs/ops/secrets.md.
• Object storage: production audit archives need S3 Object Lock/WORM semantics. The bundled MinIO exercises the integration locally; supply your own object storage with retention enforcement for production.

Self-hosting with Compose

# From the repository root:
cp .env.example .env       # edit secrets and hostnames
just dev                   # dev stack (hot reload)
# or, release images only:
just dev-release

Health checks:

just status                          # /healthz across services + infra probes
curl -fsS http://127.0.0.1:14450/healthz

Backup

For a self-hosted Compose stack, snapshot Postgres with pg_dumpall:

mkdir -p backups/$(date +%F)
docker compose --env-file .env -f compose/docker-compose.yml exec -T postgres \
  pg_dumpall -U vortex | gzip > backups/$(date +%F)/postgres.sql.gz

ClickHouse analytics data and object-storage contents (request bodies, artifacts, audit archive) need their own backup strategy; retention for the audit archive is part of the operator’s object-storage configuration. Always verify a backup by restoring it into a fresh environment before relying on it.

Helm (Kubernetes)

A thin single-node chart lives in helm/nexus. It is intended for small deployments; the chart does not configure HPA, NetworkPolicies, or PodSecurity hardening.

helm install nexus deploy/helm/nexus \
  --namespace nexus --create-namespace \
  --set ingress.host=nexus.example.com \
  --set ingress.consoleHost=console.example.com \
  --set existingSecret=nexus-secrets   # a Secret you created with strong values

The chart declares no ordering between pods, so an upgrade must roll ingest before query. ingest owns the ClickHouse schema: it applies pending migrations before it serves /healthz, and exits if they fail. query selects columns those migrations add, so a query pod that starts against a schema ingest has not yet migrated answers request list, detail, and session reads with an error until ingest catches up. The webhook exporter runs inside query and selects the same columns, so exporter polls fail for that window too and deliveries are deferred rather than lost. The Compose deployment expresses this with depends_on; on Kubernetes it is the operator’s to sequence.

See helm/nexus/values.yaml for image tags, ingress, storage sizes, and the secret contract. The chart deploys the eight Rust services and the console, plus optional single-replica data-plane helpers. MinIO and the Redis-compatible cache are disabled by default; provide external object storage with Object Lock/WORM support and a Redis-compatible endpoint for production.