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. Set up the configuration​

Clone the blueprints repository and copy the example configuration as your working directory:

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

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
  enable_rr_s3         = true
}

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

module "retool" {
  # ...
  retool_helm_chart_version = "6.11.4"
  # Remove the retool_helm_chart_use_unpublished_branch line if present

  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 state before running in production. The default local backend is not suitable for shared or long-lived 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.

If you set enable_user_ingress_https = true, the apply pauses during ACM certificate validation. While it waits, add the DNS validation CNAME record shown in the Terraform output to your current DNS provider. The apply resumes automatically once the certificate validates.

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 and ACM certificate (if not already done), and updates the Helm release to use secure cookies.

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

6. Verify the deployment​

Update your kubeconfig for the new cluster:

aws eks update-kubeconfig --name <cluster-name> --region <region>

Retrieve the cluster name from the Terraform output:

terraform output -json modules | jq -r '.["eks"].cluster.name'

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, an admin user should 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​