Reference Architectures

Sim ships a Helm chart, not infrastructure-as-code. You bring a Kubernetes cluster and, in production, managed Postgres and object storage; the chart installs Sim on top. This page draws that line precisely so you can map it onto whatever Terraform, Bicep, or CloudFormation you already run, and decide what to provision before you reach Kubernetes.

The boundary

Everything the chart can run itself, it runs by default. That is convenient for evaluation and wrong for production, because two of those defaults keep state.

The bundled Postgres uses a 10 Gi ReadWriteOnce volume and is intended for evaluation. Moving to managed Postgres is the single most important production change.

Sizing

These are the chart defaults. Memory is the constraint rather than CPU, and the app's real ceiling depends on your execution load — see Scaling for the observed steady and peak figures, when to raise app.resources.limits.memory, and how to size replicas and connection pooling. Size nodes so a single app pod fits with headroom rather than packing them.

Per-cloud requirements

Secrets

The chart offers three strategies. Pick one before you write any IaC, because it decides what your pipeline has to create.

The two non-inline modes fail in opposite directions, which is worth knowing before you pick one:

• existingSecret fails quietly. The chart renders no Secret of its own, so a key absent from yours and from app.env is simply empty at runtime. A key you also set in app.env is inlined onto the pod spec, where it shadows the Secret — so the Secret is not always the source of truth.
• External Secrets fails loudly. The chart refuses to render when a key is set in app.env but not mapped, on the grounds that a silently empty secret is worse than a failed install.

See Security for the full secret inventory, which keys are unrecoverable if lost, and what to back up.

Calling the chart from Terraform

If you already run Terraform, the chart is the resource to wrap — not something to reimplement. It is not published to a Helm repository or an OCI registry, so there is no repository to point at: vendor this repo as a submodule, a release tarball, or a git clone in your pipeline, and give chart the local path.

resource "helm_release" "sim" {
  name             = "sim"
  namespace        = "sim"
  create_namespace = true

  # Local path, not a repository. Pin the git ref you vendor from.
  chart = "${path.module}/sim/helm/sim"

  # Your own values file. The examples under helm/sim/examples/ carry
  # placeholder secrets and are starting points, not deployable as-is.
  values = [file("${path.module}/values-aws.yaml")]

  # helm provider v3 syntax. On v2 each of these is a set_sensitive { } block.
  set_sensitive = [
    { name = "app.env.BETTER_AUTH_SECRET", value = var.better_auth_secret },
    { name = "app.env.ENCRYPTION_KEY", value = var.encryption_key },
    { name = "app.env.API_ENCRYPTION_KEY", value = var.api_encryption_key },
    { name = "app.env.INTERNAL_API_SECRET", value = var.internal_api_secret },
    { name = "app.env.CRON_SECRET", value = var.cron_secret },
    # Only when the bundled Postgres is in use. With managed Postgres, set
    # externalDatabase.* and postgresql.enabled=false instead.
    { name = "postgresql.auth.password", value = var.postgres_password },
  ]
}

Because the chart is local, version does nothing — what pins it is the git ref you vendor from, and helm/sim/Chart.yaml tells you which chart release that ref carries. Pin that ref, and pin the image tags separately, or an unplanned terraform apply can move Sim to a new release with new migrations. See Upgrades.

Once the infrastructure exists, follow Kubernetes for the install itself, then the pre-launch checklist and the verification checklist.