Skip to content

ADR-020: Deployment and Private-Cloud/BYOC Architecture

  • Decision status: Accepted
  • Implementation status: Not started
  • Applies to: Enterprise/BYOC, reference runtime
  • Date: 2026-06-16
  • Deciders: Grey Newell
  • Tags: deployment, docker-compose, byoc, private-cloud, security, operations

Context

RAGhelm's product spine is private RAGOps and release control. Deployment architecture must support live demos, Docker deployment, private-cloud/BYOC artifacts, enterprise security readiness, async workers, persistence, dashboard/API boundaries, and scorecard/manifest proof bundles.

ADR-006 defines a split runtime boundary: Python owns AI runtime and TypeScript owns product gateway/dashboard APIs. ADR-015 defines SQLite local persistence and Postgres-compatible production persistence. ADR-019 defines a local async queue now with future production worker support.

The deployment architecture must be credible for demos and design partners without overcommitting to hosted SaaS before commercial packaging is decided.

This decision supports related implementation work without making issue numbers part of the durable architecture contract.

Decision

Use a staged deployment architecture:

  1. Now: multi-service Docker Compose reference deployment.
  2. Enterprise target: private-cloud/BYOC reference deployment.
  3. Hosted SaaS + BYOC hybrid: evaluate later only if the commercial roadmap demands it.

The Docker Compose deployment should be production-shaped enough to demonstrate real operations, but simple enough for local demos and design-partner pilots.

Reference Deployment Shape

Initial Docker Compose should support these logical services:

Dashboard / web UI
  -> TypeScript product gateway, when implemented
  -> Python AI runtime API
  -> local worker process
  -> SQLite or Postgres persistence
  -> artifact volume for scorecards/manifests/eval bundles
  -> configured vector/model providers

During the transition, the dashboard may call static artifacts or Python runtime endpoints directly. The target deployment shape should converge on ADR-006: dashboard and public/product APIs go through the TypeScript gateway, while Python owns AI runtime behavior.

BYOC / Private-Cloud Target

The enterprise target should support deployment in a customer's environment such that private RAG/agent data does not leave by default.

BYOC/private-cloud deployment should eventually define:

  • network boundaries
  • secrets management
  • database/storage options
  • vector backend/provider configuration
  • model provider configuration: hosted, private-cloud, or local
  • artifact storage and retention
  • worker backend option
  • ingress/auth/TLS expectations
  • backup and restore guidance
  • upgrade and rollback runbooks
  • redaction/public-proof rules

Consequences

Positive

  • Gives RAGhelm a credible deployable shape without jumping straight to enterprise complexity.
  • Supports local demos, design partners, and production-shaped testing.
  • Aligns deployment with accepted ADRs around runtime boundary, persistence, async jobs, scorecards, and manifests.
  • Preserves private-cloud/BYOC as the enterprise target.
  • Avoids premature hosted-SaaS commitments before open-core/commercial decisions.

Negative

  • Multi-service Compose is more complex than a single container.
  • BYOC remains a target, not fully solved by the first deployment milestone.
  • Hosted SaaS architecture remains undecided until commercial packaging is decided.

Neutral / Trade-offs

  • Docker Compose is not a substitute for a hardened production Kubernetes/Terraform deployment, but it is a useful reference topology.
  • Some users may run only the Python runtime locally; that remains valid for development.
  • The deployment story should be honest about which components are demo/local vs production/BYOC ready.

Alternatives Considered

  1. Local-only OSS demo

Pros: - Fastest. - Lowest operational burden.

Cons: - Not enough for private-compute, design-partner, or enterprise story.

  1. Single-container app

Pros: - Simple deployment story.

Cons: - Awkward once dashboard, gateway, Python runtime, worker, persistence, and artifact volumes are distinct concerns.

  1. Multi-service Docker Compose reference deployment

Pros: - Good initial production-shaped deployment. - Supports demos and design partners without full enterprise infrastructure.

Cons: - More moving pieces than a single-container demo.

This is the chosen initial option.

  1. BYOC/private-cloud reference deployment

Pros: - Strong enterprise story. - Aligns with private-compute positioning.

Cons: - Requires secrets, networking, storage, auth, runbooks, and deployment automation.

This is the enterprise target.

  1. Hosted SaaS + BYOC hybrid

Pros: - Strong commercial story if RAGhelm becomes a managed product.

Cons: - Premature before open-core/commercial boundary is decided.

This is deferred until commercial roadmap requires it.

Implementation Guidance

Initial Docker Compose should include or prepare for:

  • dashboard service
  • TypeScript gateway service, once implemented
  • Python runtime API service
  • local worker service
  • SQLite volume by default, with Postgres optional profile
  • artifact volume for scorecards, manifests, policies, traces, and eval bundles
  • environment variable templates
  • health checks for API/gateway/worker/db
  • smoke-test command
  • rollback instructions

Documentation should clearly label:

  • local/demo mode
  • production-shaped Docker Compose mode
  • BYOC target architecture
  • unsupported or future enterprise features

Security expectations:

  • no secrets committed
  • secrets supplied by environment or deployment secret manager
  • private source content not exported in public artifacts by default
  • production mode fails closed when required providers/config are missing
  • admin/destructive endpoints require explicit authentication and environment gating

Non-goals:

  • Kubernetes/Terraform BYOC implementation in the first deployment slice
  • hosted SaaS architecture before ADR-021 commercial boundary
  • single-container deployment as the main target architecture
  • exposing private RAG data outside the customer's environment by default

References

  • ADR-001: Product Architecture Spine for Private RAGOps Release Control
  • ADR-006: Canonical Runtime and API Boundary
  • ADR-015: Persistence Store for Release-Control History
  • ADR-019: Async Execution and Worker Queue