Requirements

Prepare these inputs before applying the selected AWS composition.

Accounts and tools

  • An AWS account and one primary AWS region.
  • AWS credentials allowed to create the VPC, load balancer, ECS, RDS, ElastiCache, S3, KMS, Secrets Manager, IAM, EC2, Auto Scaling, and optional CloudFront resources in the composition you select.
  • OpenTofu or Terraform, plus the AWS CLI, jq, OpenSSL, and curl. The repository’s Nix development shell provides the pinned project toolchain.
  • A GitHub OAuth app for browser login.
  • For Standard and Private, a customer-owned ClickHouse service reachable from Control Plane, Dispatcher and migration tasks over HTTPS. Quickstart includes local ClickHouse.

Required deployment inputs

Both infra/aws/quickstart and infra/aws/standard require:

Input Purpose
aws_region Selects regional infrastructure and the release’s worker AMI.
helmr_version Resolves the official AWS release manifest.
region_id Identifies this Helmr region.
worker_group_name Names the initial logical worker group.
platform_store_uri Points to immutable Platform Artifact objects.
platform_store_bucket_arn Authorizes access to the Platform Artifact bucket.
platform_store_kms_key_arn Authorizes decryption of Platform Artifacts.
github_oauth_client_id Non-secret OAuth application client ID.
worker_network_blocked_ipv4_cidrs Additional guest egress denies. Quickstart automatically includes its VPC, metadata and public application address; other roots require the execution VPC deny explicitly.

The Platform Artifact values come from infra/aws/modules/release-storage as a child module under an operator-owned root and backend, or from an equivalent deployment. The example compositions do not create that foundation for you. Compose infra/aws/modules/release-publisher separately when you need a publisher role, passing the exact storage outputs and your trusted IAM principals.

Quickstart additionally takes a regional Ubuntu 24.04 amd64 control_ami_id and a public app_origin. Standard and Private take external ClickHouse configuration and their own certificate/network inputs.

Release artifacts

Stable and preview common releases publish a signed release-index.json with CLI, SDK, Control Plane/builder images, and Worker host/runtime bundles. Neither publishes managed AMIs or aws-artifacts.json.

For these releases, supply the AWS compositions’ explicit controlplane_image (digest-pinned from the verified index’s Control Plane descriptor) and worker_ami_id when workers are enabled. Prepare that AMI in your deployment from the selected host/runtime bundles. Selecting helmr_version alone cannot supply those AWS-specific inputs: the generic resolver’s manifest default is not an output of the common release graph. An operator-owned AWS manifest is also an explicit preparation input; it is not a Product publication fallback.

Worker prerequisites

Workers additionally need:

  • Outbound access to the Control Plane, S3, ECR, AWS APIs, registries, and any external services your agents call.
  • KVM-capable EC2 capacity. Quickstart enables nested virtualization on a supported instance family; the production profile defaults to a metal instance.
  • A worker AMI containing worker, Firecracker, jailer, ip, nft, AWS CLI v2, curl, the systemd unit, and certified guest boot artifacts.
  • Explicit host, VM, cache, disk, and execution-slot capacity sized for the workload.
  • SSM access for maintenance unless you supply an alternative. The module does not open SSH by default.

Review workers before creating capacity.