Skip to content

Self-Hosted Deployment Guide

Overview

Deploy CloudAEye Code Review in your AWS account with the CloudAEye Terraform configuration.

This guide covers deployment options, LLM model configuration, cluster sizing, autoscaling, debug support, troubleshooting, and teardown.

Deployment Options

CloudAEye Code Review has two deployment options:

  1. SaaS - Choose this option to get CloudAEye running in minutes without managing infrastructure.
  2. Self-hosted - Choose this option when you do not want your data to leave the VPC or when you want to use your own LLM provider.

CloudAEye currently supports AWS ECS only for self-hosted Code Review.

LLM Model Configuration

Set the LLM host type, provider, and model in terraform.tfvars before running Terraform.

Use these generic Terraform variables for every deployment:

  • llm_host_type: cloudaeye or your_own.
  • llm_provider: the provider name from the catalog below.
  • llm_model: the model name from the selected provider.

Host types:

  • cloudaeye: use CloudAEye-managed LLM connectivity. No Terraform supplied provider credentials are required.
  • your_own: use your own provider account. Provider-specific credentials are required.

Supported providers and models:

Provider Supported models
OpenAI gpt-5.5, gpt-5.4
Anthropic claude-sonnet-4-6, claude-opus-4-8
AWS_Bedrock openai.gpt-5.5, openai.gpt-5.4, anthropic.claude-opus-4-8, anthropic.claude-sonnet-4-6
GCP_Vertex gemini-3.1-pro-preview, claude-sonnet-4-6, claude-opus-4-8
Azure gpt-5.5, gpt-5.4, DeepSeek-V4-Pro, glm-5.1

Recommended models:

  • claude-opus-4-8 - Claude Opus 4.8 (best performance)
  • gpt-5.4 - GPT 5.4 (best price/performance)
  • claude-sonnet-4-6 - Claude Sonnet 4.6
  • gpt-5.5 - GPT 5.5

CloudAEye-hosted example:

llm_host_type = "cloudaeye"
llm_provider  = "Anthropic"
llm_model     = "claude-opus-4-8"

Bring-your-own provider example:

llm_host_type      = "your_own"
llm_provider       = "OpenAI"
llm_model          = "gpt-5.4"
llm_openai_api_key = "sk-..."

For your_own, set the required credential variables for the selected provider:

Provider Required Terraform variables
OpenAI llm_openai_api_key
Anthropic llm_anthropic_api_key
AWS_Bedrock llm_aws_bedrock_access_key, llm_aws_bedrock_secret_key
GCP_Vertex llm_gcp_service_account_json
Azure llm_azure_api_key, llm_azure_endpoint

For GCP Vertex, llm_gcp_service_account_json must be the service account key JSON string.

Optional settings are available for provider-specific defaults: llm_aws_bedrock_region defaults to aws_region, and llm_azure_api_version defaults to 2024-02-15-preview.

Cluster Sizing Guide

Use deployment_user_count to tell Terraform the approximate number of active developers for the self-hosted deployment. Terraform uses that value to set the default always-on ECS task counts.

deployment_user_count Standard App Tasks Code Review Tasks Indexer Worker Tasks
< 20 1 1 1
20-99 1 2 2
100-299 2 3 3
300-400 2 4 4
401-999 3 6 6
1000+ 4 8 8

Standard app tasks apply to the default public application services such as the UI, API, auth, repository, webhook, and indexer API services. Code review tasks apply to cloudaeye-reviews. Indexer worker tasks apply to cloudaeye-indexer-worker.

MongoDB and ChromaDB each run as one private ECS service with one task and dedicated managed capacity. They use single ECS managed EBS volumes.

Use these Terraform settings when tuning cluster size:

  • deployment_user_count sets the default always-on task counts.
  • ecs_managed_*, mongodb_ecs_managed_*, and chroma_ecs_managed_* settings define the CPU and memory limits ECS Managed Instances can use for each capacity pool.

Autoscaling Behavior

The deployment uses ECS Managed Instances for baseline capacity. Fargate is used only as overflow capacity for autoscaled background workers.

The autoscaled services are:

  • cloudaeye-reviews, which processes the code review queue.
  • cloudaeye-indexer-worker, which processes the indexing queue.

For each autoscaled service, Terraform creates:

  • a baseline ECS service that runs on ECS Managed Instances.
  • a separate -fargate-overflow ECS service that starts at 0 tasks.
  • an Application Auto Scaling policy for the Fargate overflow service.

Application Auto Scaling changes only the Fargate overflow service desired_count. The fixed ECS Managed Instances baseline stays in place so there is always worker capacity, while burst work can scale out on Fargate.

Scaling is based on messages in the SQS queue.

Debug FAQ

Debug logging can increase CloudWatch Logs volume and cost. After collecting a support bundle, change it back to info.

Step 1: Create A Support Zip

Use the log collection script from the Terraform bundle:

python scripts/collect_cloudwatch_logs.py \
  --since 2h \
  --app-name cloudaeye \
  --environment onprem \
  --region us-east-2

The script reads CloudWatch log groups named:

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

It collects logs for the default ECS services and writes a zip file under log-bundles/, such as:

log-bundles/cloudaeye-onprem-logs-YYYYMMDDTHHMMSSZ.zip

If you use an AWS CLI profile, include it:

python scripts/collect_cloudwatch_logs.py \
  --since 2h \
  --region us-east-2 \
  --profile <aws-profile>

To collect one service at a time, use --service:

python scripts/collect_cloudwatch_logs.py \
  --since 2h \
  --service cloudaeye-reviews \
  --service cloudaeye-indexer-worker

Step 2: Send Details To Support

Email the generated zip file to:

support@cloudaeye.com

Include:

  • Detailed description of the issue you faced.
  • The approximate time the issue happened.
  • The affected repository or pull request, if relevant.
  • The Terraform app_name, environment, and AWS region.
  • Any ECS service names that were unhealthy.
  • The generated support zip from scripts/collect_cloudwatch_logs.py.

Do not email terraform.tfvars, Terraform state, private keys, API keys, or GitHub App secrets.

Troubleshooting

Application Is Not Reachable

Check:

  • allowed_app_cidr includes your current network.
  • The ALB security group allows inbound traffic on app_port.
  • The ALB endpoint matches the URL you are opening.
  • Public ECS services are healthy in the ECS console.

Services Are Not Healthy

Check ECS service events and CloudWatch logs:

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

Also verify MongoDB and ChromaDB services are running, because application services depend on private data services.

Destroy

To remove the deployment:

terraform destroy

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