docs(self-hosting): add per-cloud reference architectures

[waleedlatif1]

Summary

• Answers a recurring enterprise question — "do you have CloudFormation or Terraform templates?" — with a page instead of a per-conversation reconstruction. Sim ships a Helm chart; the chart is what your own IaC should call.
• Documents what the chart provisions by default versus what production needs you to bring, the prerequisites for EKS, AKS and GKE, how the three secret strategies map onto what your pipeline creates, and how to wrap the chart in a helm_release.

Why docs rather than a Terraform module

The one strong vendor precedent, GitLab's Environment Toolkit, lives in a separate repository and is framed as-is. Comparable products ship a chart and docs and leave the modules to the community. Maintaining Terraform across three clouds is a standing cost that buys less than documenting the boundary precisely.

Two things the page is careful about

• The Terraform snippet overrides every secret. The example values files ship literal placeholders, and the chart only rejects empty values and its own CHANGE-ME strings — so inheriting them installs cleanly with a publicly known session-signing secret.
• It states that existingSecret and External Secrets fail in opposite directions: the first silently, because app.env is inlined onto the pod spec and shadows the Secret; the second loudly, by refusing to render.

Sizing, the secret inventory and the pre-launch checklist are cross-references rather than copies, so there is one place for each to drift.

Type of Change

• Documentation

Testing

bun run lint, bun run docs-manifest:check, and MDX structural checks (frontmatter, imports, balanced Tabs/Callout, fences) pass. Every claim was verified against helm/sim/values.yaml, the three helm/sim/examples/values-*.yaml files, apps/sim/lib/uploads/config.ts, and the chart templates; the HCL was corrected after review found the original snippet could not terraform apply.

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

🤖 Generated with Claude Code

https://claude.ai/code/session_015BwsJTEQRzWJaY4BRCkPZt

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
docs	Ready	Preview	Sep 3, 2026 4:22pm UTC

[cubic-dev-ai]

2 issues found across 3 files

Confidence score: 3/5

• apps/docs/content/docs/platform/self-hosting/reference-architectures.mdx leaves AWS/GCP deployments with networkPolicy.enabled: true unable to reach managed Postgres and external Redis, which can prevent production services from functioning; document the required network policy rules or configuration.
• apps/docs/content/docs/platform/self-hosting/reference-architectures.mdx incompletely documents Pi setup, so Pi can fail closed when only the Function image is configured; specify the required E2B_PI_TEMPLATE_ID or DAYTONA_PI_SNAPSHOT_ID.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="apps/docs/content/docs/platform/self-hosting/reference-architectures.mdx">

<violation number="1" location="apps/docs/content/docs/platform/self-hosting/reference-architectures.mdx:23">
P1: When the AWS or GCP values file keeps `networkPolicy.enabled: true`, this production guidance leaves managed Postgres and external Redis unreachable because the chart only allows bundled selectors and TCP 443 by default. Document the required `networkPolicy.egress` rules, or explicitly enable `allowExternalEgress`, alongside the replacement settings.</violation>

<violation number="2" location="apps/docs/content/docs/platform/self-hosting/reference-architectures.mdx:28">
P2: When operators configure Pi, this requirement row is incomplete: Pi fails closed without its own `E2B_PI_TEMPLATE_ID` or `DAYTONA_PI_SNAPSHOT_ID`, and the Function image cannot satisfy that requirement. Document Pi's dedicated immutable image separately from the Function image.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>

[greptile-apps]

Greptile Summary

This PR adds self-hosting reference architectures for EKS, AKS, and GKE, documenting infrastructure boundaries, production prerequisites, secret-management strategies, and Terraform-based Helm deployment.

• Adds the reference architecture page to self-hosting navigation and the generated documentation manifest.
• Distinguishes chart-provided components from production-managed infrastructure.
• Updates the Terraform example to override the bundled PostgreSQL placeholder password.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
apps/docs/content/docs/platform/self-hosting/reference-architectures.mdx	Adds cloud-specific deployment guidance and correctly overrides the bundled PostgreSQL password at the Helm value path consumed by the chart.
apps/docs/content/docs/platform/self-hosting/meta.json	Adds the reference architectures page to the self-hosting documentation navigation.
apps/sim/lib/copilot/generated/docs-manifest.ts	Registers the new reference architectures document in the generated manifest.

_{Reviews (2): Last reviewed commit: 64d64e7 | Re-trigger Greptile}

[waleedlatif1]

@greptile

[waleedlatif1]

@cubic-dev-ai review this PR

[cubic-dev-ai]

@cubic-dev-ai review this PR

@waleedlatif1 I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

3 issues found across 3 files

Confidence score: 2/5

• apps/docs/content/docs/platform/self-hosting/reference-architectures.mdx gives AKS operators unsupported workload-identity guidance for Blob Storage, which can prevent uploads; document the supported AZURE_CONNECTION_STRING or AZURE_ACCOUNT_NAME configuration.
• The same reference architecture omits how to select the required dedicated Function image, leaving deployments without the needed function configuration; name E2B_FUNCTION_TEMPLATE_ID and DAYTONA_FUNCTION_SNAPSHOT_ID and document the associated variables.
• The Redis description understates the impact of losing or disabling it: pub/sub, Socket.IO collaboration, and CLI authentication lack a general fallback; distinguish these dependencies from the idempotency and execution data that can be recreated.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="apps/docs/content/docs/platform/self-hosting/reference-architectures.mdx">

<violation number="1" location="apps/docs/content/docs/platform/self-hosting/reference-architectures.mdx:24">
P2: Calling Redis a no-committed-data cache can make disabling or losing it look harmless. State that pub/sub, Socket.IO collaboration, and CLI authentication have no general fallback, while only idempotency and execution-progress markers fall back.

(Based on your team's feedback about Redis fallback scope.)</violation>

<violation number="2" location="apps/docs/content/docs/platform/self-hosting/reference-architectures.mdx:28">
P2: The row requires a dedicated Function image but does not tell operators how to select it, while the linked Security page omits those variables. Name `E2B_FUNCTION_TEMPLATE_ID`/`DAYTONA_FUNCTION_SNAPSHOT_ID` and `E2B_FUNCTION_TEMPLATE_GENERATION`, and distinguish them from Mothership images so Python and Shell can start.</violation>

<violation number="3" location="apps/docs/content/docs/platform/self-hosting/reference-architectures.mdx:92">
P1: AKS operators following this identity guidance cannot upload to Blob Storage because Sim does not authenticate Blob Storage with workload identity. Document the supported `AZURE_CONNECTION_STRING` or `AZURE_ACCOUNT_NAME` plus `AZURE_ACCOUNT_KEY` path, or add client support before recommending workload identity.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

P1: AKS operators following this identity guidance cannot upload to Blob Storage because Sim does not authenticate Blob Storage with workload identity. Document the supported AZURE_CONNECTION_STRING or AZURE_ACCOUNT_NAME plus AZURE_ACCOUNT_KEY path, or add client support before recommending workload identity.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/docs/content/docs/platform/self-hosting/reference-architectures.mdx, line 92:

<comment>AKS operators following this identity guidance cannot upload to Blob Storage because Sim does not authenticate Blob Storage with workload identity. Document the supported `AZURE_CONNECTION_STRING` or `AZURE_ACCOUNT_NAME` plus `AZURE_ACCOUNT_KEY` path, or add client support before recommending workload identity.</comment>

<file context>
@@ -0,0 +1,175 @@
+| Azure Cache for Redis | Optional |
+| GPU node pool | Only for Ollama. Taint it `sku=gpu:NoSchedule` to match the example tolerations |
+
+**Identity.** Use a workload identity bound to the ServiceAccount rather than a storage account key in `app.env`.
+
+  </Tab>
</file context>

Suggested change

	**Identity.** Use a workload identity bound to the ServiceAccount rather than a storage account key in `app.env`.
	**Identity.** Supply `AZURE_CONNECTION_STRING` or both `AZURE_ACCOUNT_NAME` and `AZURE_ACCOUNT_KEY`; the Blob client does not currently use AKS workload identity.

[cubic-dev-ai]

P2: Calling Redis a no-committed-data cache can make disabling or losing it look harmless. State that pub/sub, Socket.IO collaboration, and CLI authentication have no general fallback, while only idempotency and execution-progress markers fall back.

(Based on your team's feedback about Redis fallback scope.)

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/docs/content/docs/platform/self-hosting/reference-architectures.mdx, line 24:

<comment>Calling Redis a no-committed-data cache can make disabling or losing it look harmless. State that pub/sub, Socket.IO collaboration, and CLI authentication have no general fallback, while only idempotency and execution-progress markers fall back.

(Based on your team's feedback about Redis fallback scope.) </comment>

<file context>
@@ -0,0 +1,175 @@
+| App, realtime, migrations | Deployed | Deployed by the chart |
+| Scheduled jobs (CronJobs) | Deployed | Deployed by the chart |
+| PostgreSQL | Deployed in-cluster | **Replace** with managed Postgres — set `externalDatabase.*` and `postgresql.enabled: false` |
+| Redis | Deployed in-cluster | Replace with a managed cache, or keep the bundled one — it holds no committed data |
+| Object storage | None — local disk | **Required.** S3, Azure Blob, or GCS. Local disk is lost when a container is recreated and is not shared across replicas |
+| Ingress | Off | You install the controller; the chart renders the Ingress |
</file context>

Suggested change

	| Redis | Deployed in-cluster | Replace with a managed cache, or keep the bundled one — it holds no committed data |
	| Redis | Deployed in-cluster | Replace with a managed cache, or keep the bundled one — it holds no committed data, but pub/sub, Socket.IO collaboration, and CLI authentication have no general fallback; only idempotency and execution-progress markers fall back |

[cubic-dev-ai]

P2: The row requires a dedicated Function image but does not tell operators how to select it, while the linked Security page omits those variables. Name E2B_FUNCTION_TEMPLATE_ID/DAYTONA_FUNCTION_SNAPSHOT_ID and E2B_FUNCTION_TEMPLATE_GENERATION, and distinguish them from Mothership images so Python and Shell can start.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/docs/content/docs/platform/self-hosting/reference-architectures.mdx, line 28:

<comment>The row requires a dedicated Function image but does not tell operators how to select it, while the linked Security page omits those variables. Name `E2B_FUNCTION_TEMPLATE_ID`/`DAYTONA_FUNCTION_SNAPSHOT_ID` and `E2B_FUNCTION_TEMPLATE_GENERATION`, and distinguish them from Mothership images so Python and Shell can start.</comment>

<file context>
@@ -0,0 +1,175 @@
+| Object storage | None — local disk | **Required.** S3, Azure Blob, or GCS. Local disk is lost when a container is recreated and is not shared across replicas |
+| Ingress | Off | You install the controller; the chart renders the Ingress |
+| TLS certificates | Off | You provision them |
+| Remote sandbox | Off | Required for Python, Shell, and imported JavaScript — a provider **and** an immutable Function image. See [Security](/platform/self-hosting/security) |
+| Pi execution | Off | A separate immutable image from the Function one, pinned with `E2B_PI_TEMPLATE_ID` or `DAYTONA_PI_SNAPSHOT_ID`. Fails closed without it |
+| PII redaction, Ollama, telemetry collector | Off | Optional, off unless you enable them |
</file context>

Suggested change

	| Remote sandbox | Off | Required for Python, Shell, and imported JavaScript — a provider **and** an immutable Function image. See [Security](/platform/self-hosting/security) |
	| Remote sandbox | Off | Required for Python, Shell, and imported JavaScript — set a provider plus an immutable Function image via `E2B_FUNCTION_TEMPLATE_ID` or `DAYTONA_FUNCTION_SNAPSHOT_ID` (E2B also requires `E2B_FUNCTION_TEMPLATE_GENERATION`); keep it separate from Mothership images. See [Security](/platform/self-hosting/security) |

[waleedlatif1]

Closing in favour of #7437, which combines this with the other self-hosting PR against current staging and folds in a pre-review audit pass. Everything here is carried over — nothing dropped.