Helix StudioGenome IDE
← Docs
Helix CLI docs
Browse Helix CLI docs

Teams Deploy Guide (SRE notes)

Helix Teams v0 is a shared spine for deterministic, in‑silico work:

  • RBAC for runs and proof URLs
  • Content-addressed blob store (FS or S3-compatible)
  • Append-only audit log + deterministic audit export
  • Minimal health + metrics endpoints

This guide documents the deployment posture expected for enterprise pilots.

Components

  • Teams/Registry service: helix teams serve ... (HTTP)
  • State:
    • SQLite DB file (teams.db)
    • Blob root (FS) or S3 bucket/prefix (recommended for production)

Deployment options

Docker Compose (local + pilot baseline)

  • Source build: deploy/docker-compose.yml
  • Prebuilt image: deploy/docker-compose.image.yml

Key endpoints:

  • GET /healthz
  • GET /metrics

Kubernetes

  • Minimal manifest: deploy/k8s/helix-teams-registry.yaml (Deployment + Service).
  • Minimal Helm chart: deploy/helm/helix-teams/ (PVC + Deployment + Service + optional init Job).
  • Use managed object storage (S3) rather than in-cluster object stores for production.

If you enable the Helm chart init Job (initJob.enabled=true), the first install writes an init JSON (including adminToken) to the PVC (default: /data/teams_init.json). Treat that token as a secret and move it into your secret manager.

Configuration (high-signal)

Governance posture

  • HELIX_GOVERNANCE_MODE=enforce (recommended default)
  • Avoid HELIX_REGISTRY_ALLOW_UNREGISTERED_EXPORT in production.

Blob storage

FS mode (dev only):

  • HELIX_BLOB_BACKEND=fs
  • --blobs /data/blobs

S3 mode (recommended):

  • HELIX_BLOB_BACKEND=s3
  • HELIX_S3_BUCKET=...
  • HELIX_S3_PREFIX=... (optional)
  • HELIX_S3_STRICT_NO_OVERWRITE=1 (immutability under races; conditional put)
  • Prefer IAM/workload identity; avoid long-lived static credentials.

Auth

Teams accepts Authorization: Bearer <token>:

  • API token (stored in Teams DB; supports expiry + revocation)
  • Optional: OIDC JWT (RS256) verified against a JWKS (file/URL/discovery)

OIDC env surface is documented in Teams v0.

Metrics

  • GET /metrics serves Prometheus text format.
  • Optional hardening: set HELIX_TEAMS_METRICS_MIN_ROLE to require a bearer token with at least that role.

Backups and recovery (minimal posture)

Teams state is split across:

  • the SQLite DB file, and
  • the blob store (FS root or S3 bucket/prefix).

Recommended minimum:

  1. DB snapshots: back up the DB file on a schedule (and before upgrades).
  2. S3 versioning / immutability: enable object versioning or retention controls in the bucket if required.

Validation harness:

  • scripts/teams_smoke.sh can run a backup/restore cycle when HELIX_TEAMS_SMOKE_BACKUP_RESTORE=1.

Upgrade strategy

Teams performs additive schema upgrades on startup (new tables/columns/indexes).

Operational guidance:

  • Take a DB snapshot first.
  • Roll forward only; do not assume downgrades are safe.
  • Run release_gates.sh rc1 (and rc2/ga where applicable) before promoting a build.