Skip to main content

Deploy Retool on AWS with Terraform

Deploy a production-ready self-hosted Retool instance on AWS using Retool's Terraform blueprints.

Self-hosted Retool must be deployed on a Kubernetes cluster with Helm. For new deployments, Retool provides an officially maintained Terraform blueprint that automatically provisions all the required infrastructure (VPC, EKS cluster, RDS database, S3 bucket, load balancer, and ACM certificate) and deploys Retool using the official Helm chart.

Before you start​

1. Configure the template​

Clone the blueprints repository, confirm the example directory name, then copy it as your working directory:

git clone https://github.com/tryretool/terraform-retool-self-hosted-blueprints.git
ls terraform-retool-self-hosted-blueprints/examples/
cp -r terraform-retool-self-hosted-blueprints/examples/aws_all_inclusive_r2_beta my-retool-deployment
cd my-retool-deployment

The example directory name may change between releases. Use ls to confirm the name matches what you see in the repository before copying.

Copy the provider template:

cp provider.example.tf providers.tf

Open main.tf and update the locals block with your values:

locals {
  prefix      = "retool-prod"       # prefix for all AWS resource names
  aws_profile = "your-aws-profile"  # AWS CLI profile with sufficient permissions
  region      = "us-east-1"         # AWS region
  tags        = {}

  domain_name = "retool.example.com"  # the domain Retool will be served from

  # Start with HTTP. You will enable HTTPS after DNS is delegated.
  enable_user_ingress_https = false
}

In the retool-services module block, set your license key:

module "retool-services" {
  # ...
  license_key          = "your-license-key"
  enable_agent_sandbox = true  # required for Retool AI agents
  enable_rr_s3         = true  # required for app storage, workflow artifacts, and sandbox snapshots
}

In the retool module block, set the Helm chart version and Retool image tag. Use the latest chart version from retool-helm releases and the current stable image tag from release notes:

module "retool" {
  # ...
  retool_helm_chart_version = "6.11.0"  # check retool-helm releases for the latest

  retool_helm_extra_values = [yamlencode({
    image = {
      tag = "X.Y.Z-stable"  # replace with current stable tag
    }
  })]
}

2. Initialize Terraform​

terraform init

Terraform downloads the provider plugins and module sources.

Configure a remote backend to store Terraform state before running terraform apply. The default local backend stores state in a file on disk — if that file is lost or corrupted, you lose the ability to manage your infrastructure with Terraform. Use S3 + DynamoDB locking for production deployments.

3. Apply the configuration​

terraform apply

Review the plan and type yes to proceed. The apply provisions infrastructure in this order: VPC → EKS → RDS → Retool services → Helm release → load balancer.

The full apply takes 30–45 minutes. Most of that time is EKS cluster creation and RDS instance provisioning.

4. Configure DNS​

Once the apply completes, retrieve the Route 53 hosted zone nameservers:

terraform output -json modules | jq -r '.["user-ingress"].zone_name_servers[]'

The blueprints create a Route 53 hosted zone for your domain. Delegate your domain to it by updating the NS record at your registrar or parent DNS provider to point to these nameservers.

Retrieve the load balancer DNS name for verification:

terraform output -json modules | jq -r '.["user-ingress"].alb_dns_name'

Once DNS propagates, retool.example.com resolves to the load balancer. You can verify before full cutover using a temporary CNAME in your DNS provider:

blueprints.retool.example.com  →  <alb-dns-name>

This subdomain is created automatically by the blueprints and lets you validate the deployment before delegating the primary domain.

5. Enable HTTPS​

After DNS is delegated and propagated, enable HTTPS:

  1. In main.tf, set enable_user_ingress_https = true.
  2. Run terraform apply again. This provisions the HTTPS listener, updates the load balancer configuration, and updates the Helm release to use secure cookies.

The re-apply is significantly faster than the initial apply, typically under 5 minutes.

The blueprint provisions a wildcard ACM certificate (*.yourdomain.com) in addition to the apex certificate. The wildcard certificate is used by the agent sandbox proxy, which serves each sandbox on a unique subdomain. Terraform may pause during this re-apply while waiting for ACM to validate the certificates — add any DNS validation CNAME records shown in the output to your DNS provider. The apply resumes once validation completes.

6. Verify the deployment​

Retrieve the cluster name and region from the Terraform output, then update kubeconfig:

CLUSTER_NAME=$(terraform output -json modules | jq -r '.["eks"].cluster.name')
CLUSTER_REGION=$(terraform output -json modules | jq -r '.["eks"].cluster.region')
aws eks update-kubeconfig --name "$CLUSTER_NAME" --region "$CLUSTER_REGION"

Verify all pods are running:

kubectl get pods -n default

A healthy deployment includes pods for the core services, workflow services, and agent sandbox:

retool-api-xxx                              1/1     Running   0   5m
retool-jobs-runner-xxx                      1/1     Running   0   5m
retool-workflows-worker-xxx                 1/1     Running   0   5m
retool-workflows-backend-xxx                1/1     Running   0   5m
retool-code-executor-xxx                    1/1     Running   0   5m
retool-js-executor-xxx                      1/1     Running   0   5m
retool-agent-sandbox-controller-xxx         1/1     Running   0   5m
retool-agent-sandbox-proxy-xxx              1/1     Running   0   5m
retool-agent-sandbox-job-xxx (×5)           1/1     Running   0   5m

7. Complete setup in Retool​

Once the deployment is healthy, complete the following:

  1. Enable Temporal: click the Workflows nav item and follow the in-product setup steps. A valid license key is required. Temporal Cloud requires outbound egress on ports 443 and 7233; refer to Temporal egress.
  2. Set up Retool AI: go to Settings → AI to enable Assist, then go to Resources → AI to configure your AI provider keys.

Retool-managed AI keys are not compatible with self-hosted deployments. The managed key proxy has a 29-second timeout that agent operations regularly exceed, causing silent failures. Configure your own API keys (Bring Your Own Key) under Resources → AI.

Next steps​