> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getomni.co/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS Terraform Deployment

> Deploy Omni to AWS using Terraform for production environments

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](/deployment/docker-compose).

## Prerequisites

* AWS account with administrative access
* [Terraform](https://www.terraform.io/downloads) 1.0+
* [AWS CLI](https://aws.amazon.com/cli/) configured (`aws configure`)
* GitHub container registry access (provided during onboarding)
* Domain name for the application

## Quick Start

```bash theme={null}
# See https://github.com/getomnico/omni/releases for available versions
OMNI_VERSION="v0.1.4"
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`:

```hcl theme={null}
# 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](/deployment/configuration) for all options.

## Deploy

```bash theme={null}
terraform init
terraform plan -out=tfplan
terraform apply tfplan
```

Deployment takes 15-20 minutes. Get outputs when complete:

```bash theme={null}
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

| Component     | AWS Service       | Purpose                                                         |
| ------------- | ----------------- | --------------------------------------------------------------- |
| Compute       | ECS Fargate       | Runs all Omni services (web, searcher, indexer, ai, connectors) |
| Database      | ParadeDB on ECS   | Primary data store (PostgreSQL + pg\_search)                    |
| Cache         | ElastiCache Redis | Sessions and caching                                            |
| Load Balancer | ALB               | HTTPS termination, routing                                      |
| Network       | VPC               | Private subnets, NAT gateway                                    |
| Secrets       | Secrets Manager   | Auto-generated credentials                                      |
| Logs          | CloudWatch        | Centralized logging                                             |
| Storage       | S3                | Content and batch inference                                     |

## Scaling

```hcl theme={null}
# 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:

```bash theme={null}
# Back up your terraform.tfvars first
cp terraform.tfvars terraform.tfvars.bak
OMNI_VERSION="v0.1.4"
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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# Backup database first, then destroy
terraform destroy
```

## Troubleshooting

| Problem                    | Solution                                                                       |
| -------------------------- | ------------------------------------------------------------------------------ |
| Terraform apply fails      | Run `aws sts get-caller-identity` to verify credentials; check IAM permissions |
| ECS tasks won't start      | Check CloudWatch logs; verify image pull permissions; increase task memory     |
| Database connection errors | Verify security group allows port 5432 from ECS; check ParadeDB task status    |

See [Troubleshooting Guide](/operations/troubleshooting) for detailed diagnostics.

## Next Steps

* [Initial Setup](/deployment/initial-setup) - Configure LLMs, embeddings, and connectors
* [Connect Data Sources](/connectors/overview) - Google, Slack, Confluence
* [User Management](/admin/user-management) - Add users and permissions
* [Monitoring Setup](/admin/monitoring) - Configure alerts and dashboards