Operate with confidence

Pick the deployment shape first. Then run the stack.

This guide covers the serious self-hosted rollout path. Start with Compose when you want the smallest explicit baseline. Use Kubernetes or Helm when the cluster is already the requirement.

Self-Hosted Mode Benchmarks
Compose The smallest packaged self-hosted baseline.
Kubernetes Use the cluster path when you already operate one.
Smoke first Validate the stack with the smoke path before you trust the rollout.
Real secrets Do not boot the serious lane with placeholder values.
Chooser table

Pick the rollout shape before you copy commands.

Shape Best fit What it buys you
Compose The smallest explicit self-hosted baseline A packaged split-role stack with smokeable local ops wrappers and fewer moving parts than a cluster rollout
Raw Kubernetes manifests Teams that want the plain cluster baseline without Helm abstraction Direct control over the manifests and kustomize path
Helm Teams whose config, secrets, and release workflow already live in Helm Chart-based configuration that fits an existing cluster deployment model
Prerequisites

Have the shared services ready.

For the packaged bundle

  • Docker and Docker Compose for the packaged bundle
  • Or Kubernetes plus Helm for cluster installs

Backends you need

  • PostgreSQL
  • MinIO or another S3-compatible object store
  • Valkey
  • NATS with JetStream
Compose path

Use Compose when you want the clearest baseline.

prepare 
cd deploy/compose
cp .env.example .env
boot 
docker compose up -d
docker compose ps
docker compose logs -f urgentry-api
validate 
bash deploy/compose/smoke.sh up

Optional ClickHouse pilot

columnar profile 
printf '%s\n' \
  'COMPOSE_PROFILES=columnar' \
  'URGENTRY_BUILD_TAGS=netgo,osusergo,clickhouse' \
  'CLICKHOUSE_PASSWORD=change-me-columnar' >> .env
docker compose up -d --build

What the smoke path now does

  • Builds the shared urgentry:latest image once per run
  • Reuses that image across the split-role stack
  • Verifies the logs bridge when the ClickHouse pilot is enabled
Operator commands

Run the same control-plane operations either way.

binary commands 
./urgentry self-hosted preflight --control-dsn "$URGENTRY_CONTROL_DATABASE_URL" --telemetry-dsn "$URGENTRY_TELEMETRY_DATABASE_URL"
./urgentry self-hosted status --control-dsn "$URGENTRY_CONTROL_DATABASE_URL" --telemetry-dsn "$URGENTRY_TELEMETRY_DATABASE_URL"
./urgentry self-hosted maintenance-status --control-dsn "$URGENTRY_CONTROL_DATABASE_URL"
compose wrapper 
bash deploy/compose/ops.sh preflight
bash deploy/compose/ops.sh status
bash deploy/compose/ops.sh maintenance-status
Backup and upgrade

Keep restore and rollback close to the rollout plan.

backup, restore, upgrade 
bash deploy/compose/backup.sh /tmp/urgentry-backup
bash deploy/compose/restore.sh /tmp/urgentry-backup
bash deploy/compose/upgrade.sh

Next docs

Use the Kubernetes and Helm guide if you are going cluster-first, the HA baseline if you are checking posture, or maintenance mode if you are writing the operator runbook.

Kubernetes and Helm HA Baseline Maintenance Mode