Skip to main content
Deploy Omni to AWS using Terraform for production-ready infrastructure with auto-scaling and multi-AZ redundancy. For development or single-server deployments, see Docker Compose Deployment.

​
Prerequisites

  • AWS account with administrative access
  • Terraform 1.0+
  • AWS CLI configured (aws configure)
  • GitHub container registry access (provided during onboarding)
  • Domain name for the application

​
Quick Start

# See https://github.com/getomnico/omni/releases for available versions
OMNI_VERSION="v0.5.0"
curl -fsSL "https://github.com/getomnico/omni/releases/download/${OMNI_VERSION}/omni-terraform-aws.tar.gz" \
  | tar xz
cd terraform-aws
cp terraform.tfvars.example terraform.tfvars
Edit terraform.tfvars: 
# Required
customer_name     = "acme-corp"           # Lowercase, hyphens only
github_org        = "omni-platform"
embedding_api_key = "your-embedding-api-key-here"
custom_domain     = "omni.<your domain>.com"

# Optional: AWS Configuration
region      = "us-east-1"
environment = "production"

# Optional: Database Configuration
paradedb_instance_type = "t3.small"       # Default
paradedb_volume_size   = 50               # GB, default

# Optional: Cache Configuration
redis_node_type      = "cache.t3.micro"
redis_engine_version = "7.1"

# Optional: ECS Configuration
ecs_task_cpu      = "512"
ecs_task_memory   = "1024"
ecs_desired_count = 1

# Optional: SSL (leave empty for HTTP-only)
# ssl_certificate_arn = "arn:aws:acm:us-east-1:xxx:certificate/xxx"

# Optional: Monitoring
log_retention_days = 30

# Optional: AI Service Configuration
# embedding_provider      = "jina"
# embedding_model         = "jina-embeddings-v3"
# embedding_dimensions    = "1024"
# embedding_max_model_len = "8192"
See Configuration Reference for all options.

​
Deploy

terraform init
terraform plan -out=tfplan
terraform apply tfplan
Deployment takes 15-20 minutes. Get outputs when complete: 
terraform output omni_url        # Application URL
terraform output alb_dns_name    # For DNS CNAME record
Create a CNAME record pointing your domain to the ALB DNS name, then access at https://omni.<your domain>.com.

​
Infrastructure Overview

ComponentAWS ServicePurpose
ComputeECS FargateRuns all Omni services (web, searcher, indexer, ai, connectors)
DatabaseParadeDB on ECSPrimary data store (PostgreSQL + pg_search)
CacheElastiCache RedisSessions and caching
Load BalancerALBHTTPS termination, routing
NetworkVPCPrivate subnets, NAT gateway
SecretsSecrets ManagerAuto-generated credentials
LogsCloudWatchCentralized logging
StorageS3Content and batch inference

​
Scaling

# Vertical: increase task resources (defaults: cpu="512", memory="1024")
ecs_task_cpu    = "2048"    # 2 vCPU
ecs_task_memory = "4096"    # 4 GB

# Horizontal: more tasks per service (default: 1)
ecs_desired_count = 3
Apply with terraform apply.

​
Updating

Re-download the Terraform artifact for the new release and re-apply: 
# Back up your terraform.tfvars first
cp terraform.tfvars terraform.tfvars.bak
OMNI_VERSION="v0.6.0"
curl -fsSL "https://github.com/getomnico/omni/releases/download/${OMNI_VERSION}/omni-terraform-aws.tar.gz" \
  | tar xz
cd terraform-aws
cp ../terraform.tfvars.bak terraform.tfvars
terraform plan -out=tfplan
terraform apply tfplan

​
Backups

# Get a running task ID
TASK_ID=$(aws ecs list-tasks --cluster $(terraform output -raw ecs_cluster_name) \
  --service-name paradedb --query 'taskArns[0]' --output text)

# Run backup (uploads to S3 directly from container)
aws ecs execute-command \
  --cluster $(terraform output -raw ecs_cluster_name) \
  --task $TASK_ID \
  --container paradedb \
  --interactive \
  --command "/bin/bash -c 'pg_dump -U omni omni | gzip | aws s3 cp - s3://your-backup-bucket/backup-\$(date +%Y%m%d).sql.gz'"

​
Monitoring

# Tail logs
aws logs tail $(terraform output -raw log_group_name) --follow

# Filter errors
aws logs filter-log-events \
  --log-group-name $(terraform output -raw log_group_name) \
  --filter-pattern "ERROR"
Container Insights is enabled by default for ECS metrics. Use log_retention_days (default: 30) to control CloudWatch log retention.

​
Destroying

# Backup database first, then destroy
terraform destroy

​
Troubleshooting

ProblemSolution
Terraform apply failsRun aws sts get-caller-identity to verify credentials; check IAM permissions
ECS tasks won’t startCheck CloudWatch logs; verify image pull permissions; increase task memory
Database connection errorsVerify security group allows port 5432 from ECS; check ParadeDB task status
See Troubleshooting Guide for detailed diagnostics.

​
Next Steps