AWS Terraform reference

The AWS Terraform reference shows the production-style way to run Qodex. It uses one Docker image across multiple ECS services, stores relational data in RDS Postgres, stores artifacts in S3, and routes traffic through an HTTPS Application Load Balancer.

What the reference creates

Resource	Purpose
VPC and subnets	Public subnets for the load balancer and private subnets for ECS and RDS.
Application Load Balancer	Terminates HTTPS and forwards traffic to Qodex on port `3000`.
ECS Fargate	Runs the Qodex web, worker, and scheduler services.
RDS Postgres	Stores Qodex product state.
ECR	Stores the Qodex Docker image.
S3	Stores screenshots, videos, DOM snapshots, logs, and attachments.
CloudWatch Logs	Captures service logs with retention.
Security groups	Restrict public access to the ALB and private access between ECS and RDS.

The reference is single-region and starts with one desired task for each ECS service.

Production layout

Internet
  |
  v
Route 53
  |
  v
ACM certificate
  |
  v
Application Load Balancer (public subnets)
  |
  v
ECS Fargate services (private subnets)
  |
  +-- RDS Postgres
  +-- S3 artifact bucket
  +-- OpenAI API through NAT
  +-- CloudWatch Logs

ECS services

The production reference splits one image into three services:

Service	Role
Web	Runs the Hono HTTP and WebSocket server. The ALB points here.
Worker	Processes agent runs and test executions when Redis queue mode is enabled.
Scheduler	Runs scheduled scans when Redis queue mode is enabled.

For smaller deployments, Qodex can run scheduler and worker behavior in-process without Redis. The split-service shape is the production posture.

Apply Terraform

From the Terraform directory in the infrastructure repo:

terraform init
terraform plan
terraform apply

The first apply takes longer because RDS needs to provision. Later applies are usually faster. For a known small change, such as updating one ECS task definition, you can target the specific resources instead of planning the full stack.

Deploying application changes

The production deploy builds the Docker image, pushes it to ECR, registers new task revisions, and rolls out the ECS services. Use a pinned image tag or release SHA so you can trace which version is running.

Secrets and environment variables

The ECS task definitions inject the same variables described in Environment variables. For stronger production posture, store sensitive values in AWS Secrets Manager and grant the ECS task role permission to read them instead of placing secret values directly in Terraform variables.

What to customize before using this in your account

Replace all secrets.
Choose your own domain and ACM certificate.
Decide whether to keep single-region or add a disaster recovery plan.
Add RDS backup and retention policies that match your compliance needs.
Add S3 lifecycle policies for artifact retention.
Decide whether to add autoscaling for web and worker services.

Next steps

Environment variables

Configure the ECS task environment.

Storage backends

Understand the S3 artifact bucket.

Secret management

Protect BYOK keys and OAuth credentials.

Single-container deploy

Compare with the smaller Docker path.

Docker Compose Environment variables

​AWS Terraform reference

​What the reference creates

​Production layout

​ECS services

​Apply Terraform

​Deploying application changes

​Secrets and environment variables

​What to customize before using this in your account

​Next steps