Self-Hosted Deployment Guide¶

Deploy CloudAEye Code Review in your AWS account with the CloudAEye Terraform configuration. The stack creates the network, ECS Managed Instances cluster, application services, data services, user pool, queues, and logging required for a self-hosted deployment.

What Gets Created¶

Resource	Purpose
VPC, public subnet, private subnet	Isolated network for the deployment
Internet gateway and NAT gateway	Public load balancer access and private ECS outbound access
Application Load Balancer	Public entry point for CloudAEye routes
ECS cluster with ECS Managed Instances	Runtime for application containers and data services
MongoDB ECS service	Internal database for CloudAEye application data
ChromaDB ECS service	Internal vector database
ECS managed EBS volumes	Persistent storage for MongoDB and ChromaDB
Cloud Map private DNS	Internal service discovery for MongoDB and ChromaDB
SQS queues	`cloudaeye-indexing-queue` for indexing work and `cloudaeye-review-queue` for asynchronous review work
Cognito user pool and identity resources	Tenant user authentication and bootstrap setup
CloudWatch log groups	Logs for application, data, and bootstrap tasks

MongoDB and ChromaDB are private services and are not exposed through the public load balancer.

Terraform Bundle Files¶

CloudAEye provides the Terraform configuration as zip. The configuration includes only the deployable Terraform configuration and example input files.

File	What it contains
`providers.tf`	AWS provider configuration.
`terraform.tf`	Terraform and provider version constraints.
`variables.tf`	Input variables for AWS region, networking, tenant bootstrap, GitHub App values, LLM settings, ECS sizing, data volumes, and autoscaling.
`terraform.tfvars.example`	Example customer input file to copy to `terraform.tfvars` locally.
`locals.tf`	Derived names, default ECS service definitions, task counts from `deployment_user_count`, environment variables, service routes, and shared tags.
`main.tf`	Core infrastructure: VPC, public/private subnets, internet gateway, NAT gateway, route tables, security groups, SQS queues, Cognito CloudFormation stack, Cloud Map private DNS, and load balancer routing.
`ecs.tf`	ECS cluster, ECS Managed Instances capacity providers, CloudWatch log groups, task definitions, ECS services, MongoDB and ChromaDB volumes, bootstrap task, and worker autoscaling.
`iam.tf`	IAM roles and policies for ECS task execution, application tasks, ECS infrastructure, managed instances, SQS access, Cognito bootstrap, and ECS managed EBS volumes.
`outputs.tf`	Deployment outputs such as ECS cluster name, ALB DNS name, app URL, service routes, internal data service DNS names, queue URLs.
`NewTenantPoolONLY.template`	CloudFormation template used by Terraform to create the Cognito user pool, app client, identity pool, groups, and Cognito IAM roles.

Prerequisites¶

Before you deploy, confirm you have:

Linux shell.
Terraform 1.15.5.
AWS CLI configured for the customer AWS account.
AWS permissions to create VPC, EC2, ECS, Elastic Load Balancing, IAM, EBS, SQS, Cognito, CloudWatch, Cloud Map, and related resources.
Tenant admin details for the first admin user.

Create a GitHub App for the self-hosted Code Review integration:

GitHub App setting	Value
Webhook URL	`http://<alb-dns-name>/github-app/webhook`
Events	Pull request, Push, Issue comment

Set these GitHub App permissions:

Permission	Access
Checks	Read and write
Commit statuses	Read
Contents	Read
Issues	Read and write
Pull requests	Read and write

Collect these GitHub App values before deployment:

App ID
Client ID
Client Secret
Private Key
Webhook Secret

Setup¶

Go to the Terraform deployment bundle:

cd /path/to/on-prem-deployment

Create your local variables file:

cp terraform.tfvars.example terraform.tfvars

Edit terraform.tfvars and set the exact values:

Setting	Description
`aws_region`	AWS region for the deployment
`aws_profile`	Optional local AWS profile
`allowed_app_cidr`	CIDR allowed to access the public load balancer
`mongodb_password`	MongoDB root password used by the private MongoDB service
`server_x_api_key`	API key passed to CloudAEye application containers
`openai_api_key`	OpenAI API key used by Code Review services
`tenant_key`, `tenant_identifier`	Tenant identity values for the self-hosted install
`tenant_admin_*`	Initial tenant admin user details
`github_*`	GitHub App ID, client ID, client secret, installation ID, private key, app key, and webhook secret

Deploy¶

Run Terraform:

terraform init
terraform validate
terraform plan
terraform apply

Review the plan before applying. On the first apply, Terraform creates the infrastructure, starts the ECS services, and runs a one time auth bootstrap task after Cognito and ECS are ready.

The bootstrap task creates or updates the on-prem tenant, admin user, Cognito admin user, and LLM details inside the deployed MongoDB service.

Access¶

After terraform apply completes, get the application URL:

terraform output app_base_url

You can also inspect the load balancer DNS name and public routes:

terraform output alb_dns_name
terraform output service_routes

Public paths:

Route	Service
`/*`	`cloudaeye-web`
`/code-review/*`	`cloudaeye-reviews`
`/rca/test/*`	`cloudaeye-api`
`/rca/code-repository-integration/*`	`cloudaeye-repositories`
`/external-service/*`	`cloudaeye-indexer-api`
`/secret-scanner/*`	`cloudaeye-secrets`
`/sso/*`	`cloudaeye-auth`
`/github-app/webhook`	`cloudaeye-webhook`

The cloudaeye-indexer-worker, MongoDB, and ChromaDB services are private and are not exposed through the load balancer.

Configuration¶

Most customer-specific configuration is handled through terraform.tfvars.

To restrict access to the public application, set allowed_app_cidr to your office or CIDR:

allowed_app_cidr = "203.0.113.10/32"

For advanced deployments, the ecs_services map can override service images, CPU, memory, desired count, commands, route paths, and health check paths. Use this only after consulting CloudAEye.

Operations¶

List ECS services:

aws ecs list-services \
  --cluster "$(terraform output -raw ecs_cluster_name)"

Describe a service:

aws ecs describe-services \
  --cluster "$(terraform output -raw ecs_cluster_name)" \
  --services <service-name>

CloudWatch log groups are created under:

/ecs/<app_name>-<environment>/<service-name>

Destroy¶

To remove the deployment:

terraform destroy

This deletes the infrastructure created by the stack, including ECS services and the EBS data volumes. Export or back up any required data before destroying the deployment.