HypercubsDRC Docs
how-to operator public

Deploy DRC

Choose hosted DRC for a managed workspace, self-managed DRC when your organization operates the service and its data authorities, or the local CLI/runtime for customer-controlled capture and replay. The distinct customer-controlled metadata sync bridge is documented in Customer-controlled data plane.

Self-managed topology

Private Cloud and air-gapped deployments use the supported Helm or Compose distribution package supplied for your deployment. The deployment can be restricted to internal-DNS-only and proxy-only network paths, with data residency and object-store replication selected by the operator. Use the versioned customer deployment package and its release-specific values.

Your DRC representative provides the current package. Instructions that reference internal source, build, or CI paths are not part of the customer installation contract; follow the values and runbooks that ship with the package you received.

The supported self-managed topology is:


clients and capture agents
        ↓ TLS
DRC API replicas ───── PostgreSQL
        │                 │
        └──────────── immutable object storage
                         │
                    DRC workers

PostgreSQL is the control-plane authority and stores bounded pending capture receipts plus hosted security-coordination state. Object storage is the immutable artifact authority after the upload and database link are verified.

Install with the supported path

Use the on-prem Compose or Helm deployment supplied with the release. Provide explicit values for:

  • DRC_PROCESS_ROLE=api, worker, or migration as appropriate
  • PostgreSQL connection and migration ownership
  • immutable artifact-store endpoint and credentials
  • TLS certificate and key references
  • managed evidence and signing-key references
  • API bind address and public URL
  • DRC_DEPLOYMENT_GENERATION for the rollout
  • stable DRC_API_INSTANCE_ID values for every API replica
  • matching DRC_EXPECTED_API_INSTANCES on workers; legacy artifact-role removal remains blocked until every expected replica is live on the same generation. The supported Compose packages default this to DRC_API_INSTANCE_ID, which covers the single-replica case; set it explicitly to a comma-separated list only when you run more than one replica. The worker names the exact mismatch in its log, so a value that no replica registers is reported as such instead of as a capability failure.

Run the distribution package’s preflight, migration, and smoke-test commands in order. The checks fail closed when a required authority is missing. A passing configuration check is not a substitute for a staging failure-recovery test.

For a private release, keep container registry credentials and any image overrides in the deployment environment rather than committing them. Record the exact image digests or release tags in the rollout record before starting customer workloads.

For an operator-installed Kubernetes deployment, apply the manifests with the target cluster chosen explicitly in every command, either as kubectl --context CONTEXT or via DRC_KUBE_CONTEXT where the deployment tooling reads it; do not rely on the ambient current kubectl context. Set validated DRC_OPERATOR_IMAGE and DRC_SHARD_IMAGE references for private registries, Verify the image signatures/provenance and resolved digests against the release manifest before applying them. If your organization must build private container images, use its approved image build and publishing process; configure DRC_API_IMAGE_REPOSITORY, DRC_OPERATOR_IMAGE, and DRC_SHARD_IMAGE to the immutable images it produces. Do not disable TLS verification or trust checks to work around a certificate failure.

Scaling

Scale API replicas independently from workers. Keep PostgreSQL connection limits, object-store throughput, WAL disk pressure, and worker concurrency within the values tested by your deployment.

Every API and worker process opens its own pool, capped by DRC_DATABASE_MAX_CONNECTIONS (default 5). Size that cap against the *whole* deployment: replicas multiply it, and a rolling restart briefly overlaps old and new processes. A managed pooler in session mode that allows 15 clients for the project is exhausted by two processes asking for 20 connections each, which surfaces as EMAXCONNSESSION failures from whichever worker cycle runs next. Do not advertise a throughput or availability target without matching evidence from your environment.

Host capacity and container logs

Every service in the supported Compose package bounds its json-file log at 10 MiB across three files, and the API and worker get a 30-second stop window so a redeploy retires their heartbeats instead of leaving a stale replica in the readiness gate. Keep both properties when you extend the package: an unbounded container log is the fastest way for a host that has spare capacity today to run out of it during an incident, and a killed replica advertises a generation it no longer serves until its heartbeat expires.

Inspect and reclaim with the host's own tooling:


docker system df                      # images, containers, volumes, build cache
docker builder prune                  # build cache left by on-host builds
docker container prune                # stopped containers and their writable layers
docker image prune                    # dangling layers only
journalctl --vacuum-size=100M        # systemd journal

Reclaim build cache, stopped containers, and dangling layers freely. Before removing a tagged image, confirm that no running container uses it and that it is not the rollback target for the current deployment. Never delete PostgreSQL data, WAL segments, object-store objects, or signing keys to recover space; the storage they occupy is the evidence the product exists to keep.

Build release images in CI from drc-rust/Dockerfile.api and deploy the tagged result. Building an API image on the host that serves traffic leaves the registry cache, build cache, and per-architecture toolchain copies on that host, which is where most of the space goes and where it is least expected.

Deployment trust and certificate updates

TLS clients do not all use the same certificate verifier. Keep host CA bundles and language-specific/bundled TLS trust stores current, rebuild container images after certificate-package security updates, and restart applications that embed a trust store. Test the actual application connection path rather than assuming that a browser or curl result covers every runtime. Never work around certificate errors by disabling certificate or hostname verification.

The DRC Node packages require Node.js 22.23.4, 24.22.1, or 26.12.1 and later releases on the corresponding release line. Keep the runtime and trust data current, and verify TLS using the actual DRC client path. See Security update guidance for client and deployment requirements.

Backups and recovery

Back up PostgreSQL, WAL, and immutable evidence artifacts under one retention policy. Test restore into an isolated environment, replay a known verification workload, and record measured RPO/RTO before relying on the backup.

Upgrades

Apply migrations before starting a binary that requires them. The Helm API workload uses a StatefulSet with stable ordinal identities; releases that previously used the Deployment-based API workload require a controlled migration because Kubernetes does not change a resource kind in place. Drain the old API workload, preserve the existing Service name, install the new StatefulSet/headless governing Service, and verify all expected API heartbeats before enabling legacy-role removal. Never delete old evidence or signing keys as part of a normal application rollback.