Getting Started

Deploy an EVM blockchain indexer on AWS in under 10 minutes. This guide uses the simplest example: EC2 + Docker Compose + external ClickHouse.

What You're About to Build

Prerequisites

Optional (for development/QA):

AWS Credentials

Configure AWS CLI with credentials that have EC2, VPC, IAM, and Secrets Manager permissions:

aws configure
# Or export environment variables:
export AWS_ACCESS_KEY_ID=your-key
export AWS_SECRET_ACCESS_KEY=your-secret
export AWS_DEFAULT_REGION=us-east-1

SSH Key

If you don't have one:

ssh-keygen -t ed25519 -C "evm-cloud" -f ~/.ssh/evm-cloud
# Public key: ~/.ssh/evm-cloud.pub
# Private key: ~/.ssh/evm-cloud

Your First Deployment

We'll use the minimal_aws_byo_clickhouse example — EC2 instance running eRPC + rindexer with an external ClickHouse database.

1. Clone and Navigate

git clone https://github.com/ExoMonk/evm-cloud.git
cd evm-cloud/examples/minimal_aws_byo_clickhouse

2. Configure Secrets

cp secrets.auto.tfvars.example secrets.auto.tfvars

Edit secrets.auto.tfvars with your values:

# SSH key (the public key content, not the path)
ssh_public_key = "ssh-ed25519 AAAA... your-email"
 
# ClickHouse connection (from ClickHouse Cloud or your own instance)
indexer_clickhouse_url      = "https://your-instance.clickhouse.cloud:8443"
indexer_clickhouse_password = "your-password"

Don't have ClickHouse? Sign up for ClickHouse Cloud free tier, or use the minimal_aws_rds example instead (uses managed PostgreSQL, no external DB needed).

3. Initialize and Plan

terraform init
terraform plan -var-file=minimal_clickhouse.tfvars

Review the plan. You should see resources for:

• VPC, subnets, security groups
• EC2 instance (t3.micro — AWS free tier eligible)
• IAM role + Secrets Manager secret
• Docker Compose services (eRPC + rindexer)

4. Apply

terraform apply -var-file=minimal_clickhouse.tfvars

This takes 3-5 minutes. Terraform will:

1. Create a VPC with public subnets
2. Launch an EC2 instance with Docker pre-installed
3. Deploy eRPC (RPC proxy) and rindexer (indexer) as Docker containers
4. Wire rindexer to your ClickHouse database via Secrets Manager

5. Verify

# Get the instance IP
terraform output -json workload_handoff | jq -r '.runtime.ec2.public_ip'
 
# SSH into the instance
ssh -i ~/.ssh/evm-cloud ubuntu@<public-ip>
 
# Check containers are running
sudo docker compose -f /opt/evm-cloud/docker-compose.yml ps

You should see erpc and rindexer containers in running state.

6. Teardown

terraform destroy -var-file=minimal_clickhouse.tfvars

What Just Happened

Here's what Terraform created and how data flows:

• eRPC aggregates multiple RPC endpoints with automatic failover, caching, and load balancing
• rindexer reads your rindexer.yaml config to index specific contracts/events into your database
• Secrets Manager securely stores database credentials and injects them at runtime

Next Steps

• Try a different example: See Examples for all 7 deployment patterns
• Understand the architecture: Read Architecture and Core Concepts
• Tune performance: See Variable Reference for instance types, memory limits, and other knobs
• Go to production: Follow the Production Checklist

Other Starting Points