Reference architectures

Provision a Kubernetes cluster, durable database storage, object storage, networking, and secrets before installing Sim. The Helm chart installs application workloads on that infrastructure; it does not provision cloud resources.

There is no official Terraform module or CloudFormation template. Call the chart from your infrastructure as code (IaC), for example with Terraform's helm_release or a Helm pipeline task.

The boundary

The chart bundles PostgreSQL and Redis for evaluation. For production, decide how each stateful dependency is backed up, restored, and made available.

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.

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.

Non-inline modes handle missing keys differently:

• 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.

Sizing

These are chart defaults, not capacity benchmarks. Measure memory, CPU, execution concurrency, and database connections with representative workloads. See Scaling for pool budgets and sizing estimates. A node must fit an app pod plus system overhead.

Calling the chart from Terraform

If you already run Terraform, the chart is the resource to wrap — not something to reimplement. Point repository at the OCI registry and pin version; there is no need to vendor the repo.

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

  # Always pin `version`. Without it Terraform resolves the newest published
  # chart at apply time, which is how an unplanned apply moves Sim to a new
  # release with new migrations.
  repository = "oci://ghcr.io/simstudioai/charts"
  chart      = "sim"
  version    = "1.11.8"

  # Or the classic repository, if your tooling does not speak OCI:
  #   repository = "https://charts.sim.ai"

  # 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 },
  ]
}

Pin version above. Empty image tags use the selected chart's appVersion, so a pinned chart also selects that default app version. Explicit image tags or digests override it; pin them separately when you need that control, and keep app, realtime, and migrations aligned. Chart 1.11.8 was published with app version v0.9.17; local checkout metadata can differ. See Upgrades.

Related docs

• Install with Kubernetes
• Pre-launch checklist
• Verify your install