Infrastructure Setup

Deploy the complete SuperBox AWS infrastructure using OpenTofu or Terraform. This guide walks through installation, configuration, and deployment.

Prerequisites

AWS Account

Active AWS account with billing enabled
Programmatic access (Access Key ID + Secret Access Key)
Permissions to create: S3, Lambda, IAM, CloudWatch resources
Recommended: Admin access or custom IAM policy

OpenTofu/Terraform

OpenTofu (Recommended):

# Windows
winget install OpenTofu.tofu

# macOS
brew install opentofu

# Linux
curl -fsSL https://get.opentofu.org/install-opentofu.sh | bash

Terraform (Alternative):

# Download from https://www.terraform.io/downloads
# Extract and add to PATH
terraform version

AWS CLI (Optional)

For verification and testing:

# Install AWS CLI 
pip install awscli
# Configure credentials 
aws configure

Step 1: Get AWS Credentials

Access IAM Console

Navigate to AWS Console → IAM → Users → Select your user

Create Access Key

Go to Security Credentials tab
Click Create Access Key
Choose CLI/SDK as use case
Download or copy the credentials

Store Securely

# Never commit these to git!
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

Keep your AWS credentials secure. Use AWS Secrets Manager or environment variables. Never commit terraform.tfvars to version control.

Step 2: Package Lambda Function

The Lambda function (lambda.py) must be packaged before deployment.

PowerShell (Windows)
Bash (Linux/macOS)

# Navigate to scripts directory
cd SuperBox-Infra/scripts

# Run packaging script
.\package_lambda.ps1

# Verify output
ls ../modules/lambda/lambda_payload.zip

# Navigate to scripts directory
cd SuperBox-Infra/scripts

# Make script executable
chmod +x package_lambda.sh

# Run packaging script
./package_lambda.sh

# Verify output
ls -lh ../modules/lambda/lambda_payload.zip

This creates modules/lambda/lambda_payload.zip containing lambda.py and its dependencies.

Step 3: Configure Variables

Create SuperBox-Infra/terraform.tfvars:

# AWS Credentials
aws_access_key = "YOUR_AWS_ACCESS_KEY_ID"
aws_secret_key = "YOUR_AWS_SECRET_ACCESS_KEY"

# Deployment Configuration
aws_region   = "ap-south-1"  # Mumbai (change as needed)
project_name = "superbox"

# Lambda Configuration (optional)
lambda_runtime     = "python3.11"
lambda_memory_size = 2048       # MB
lambda_timeout     = 900        # 15 minutes
log_retention_days = 7          # CloudWatch retention

Available AWS Regions

Asia Pacific:

ap-south-1 (Mumbai)
ap-southeast-1 (Singapore)
ap-northeast-1 (Tokyo)

US:

ap-south-1 (Mumbai) - Recommended
us-east-1 (N. Virginia)
us-west-2 (Oregon)

Europe:

eu-west-1 (Ireland)
eu-central-1 (Frankfurt)

Choose the region closest to your users for lower latency.

Step 4: Initialize Infrastructure

Navigate to Infrastructure Directory

cd SuperBox-Infra

Initialize OpenTofu/Terraform

# OpenTofu
tofu init

# OR Terraform
terraform init

This downloads required providers and initializes backend.Expected Output:

Initializing modules...
Initializing the backend...
Initializing provider plugins...
- Finding latest version of hashicorp/aws...
- Installing hashicorp/aws v5.x.x...

OpenTofu has been successfully initialized!

Validate Configuration

# OpenTofu
tofu validate

# OR Terraform
terraform validate

Ensures configuration syntax is correct.

Step 5: Plan Deployment

Review infrastructure changes before applying:

# OpenTofu
tofu plan -out=tfplan

# OR Terraform
terraform plan -out=tfplan

Expected Resources:

Plan: 10+ to add, 0 to change, 0 to destroy.

Resources to create:
  + aws_s3_bucket.registry
  + aws_iam_role.lambda_execution
  + aws_iam_role_policy.lambda_s3_access
  + aws_lambda_function.mcp_executor
  + aws_apigatewayv2_api.websocket
  + aws_apigatewayv2_integration.lambda
  + aws_apigatewayv2_route (connect, disconnect, default)
  + aws_apigatewayv2_stage.production
  + aws_cloudwatch_log_group.lambda_logs

Review the plan carefully. Verify bucket names, IAM permissions, WebSocket API Gateway, and Lambda configuration match your requirements.

Step 6: Deploy Infrastructure

Apply the planned changes:

# OpenTofu
tofu apply tfplan

# OR Terraform
terraform apply tfplan

Deployment Progress:

aws_s3_bucket.registry: Creating...
aws_iam_role.lambda_execution: Creating...
aws_s3_bucket.registry: Creation complete [10s]
aws_iam_role.lambda_execution: Creation complete [5s]
aws_lambda_function.mcp_executor: Creating...
aws_lambda_function.mcp_executor: Creation complete [30s]
aws_apigatewayv2_api.websocket: Creating...
aws_apigatewayv2_api.websocket: Creation complete [5s]
aws_apigatewayv2_integration.lambda: Creating...
aws_apigatewayv2_route.connect: Creating...
aws_apigatewayv2_route.disconnect: Creating...
aws_apigatewayv2_route.default: Creating...
aws_apigatewayv2_stage.production: Creating...
aws_apigatewayv2_stage.production: Creation complete [2s]

Apply complete! Resources: 10+ added, 0 changed, 0 destroyed.

⏱️ Estimated Time: 2-3 minutes

Step 7: Retrieve Outputs

Get deployed resource information:

# OpenTofu
tofu output

# OR Terraform
terraform output

Example Output:

websocket_url = "wss://abc123xyz.execute-api.ap-south-1.amazonaws.com/production"
s3_bucket_name = "superbox-mcp-registry"
lambda_function_name = "superbox-mcp-executor"
lambda_function_arn = "arn:aws:lambda:ap-south-1:123456789:function:superbox-mcp-executor"
cloudwatch_log_group = "/aws/lambda/superbox-mcp-executor"
aws_region = "ap-south-1"

Save the websocket_url - you’ll need it for the backend CLI configuration as WEBSOCKET_URL.

Step 8: Test Deployment

Verify infrastructure is working:

Test WebSocket Connection
Test S3 Bucket
Check CloudWatch Logs

# Get WebSocket URL from outputs
WS_URL=$(tofu output -raw websocket_url)

# Test using wscat (install: npm i -g wscat)
wscat -c "$WS_URL?test_mode=true&repo_url=https://github.com/user/test-mcp&entrypoint=main.py&lang=python"

Expected: WebSocket connection established, Lambda logs show connection

# Get bucket name
BUCKET=$(tofu output -raw s3_bucket_name)

# List objects (should be empty)
aws s3 ls s3://$BUCKET/

# Upload test file
echo '{"test": "data"}' > test.json
aws s3 cp test.json s3://$BUCKET/test.json

# Verify upload
aws s3 ls s3://$BUCKET/

# View recent logs
aws logs tail /aws/lambda/superbox-mcp-executor --follow

# Or via AWS Console
# CloudWatch → Logs → Log groups → /aws/lambda/superbox-mcp-executor

Configuration for Backend

Update backend .env file with deployed infrastructure:

# superbox.ai/.env

# AWS Configuration
AWS_REGION=ap-south-1
S3_BUCKET_NAME=superbox-mcp-registry
WEBSOCKET_URL=wss://abc123xyz.execute-api.ap-south-1.amazonaws.com/production

# AWS Credentials (for S3 access)
AWS_ACCESS_KEY_ID=YOUR_ACCESS_KEY
AWS_SECRET_ACCESS_KEY=YOUR_SECRET_KEY

Updating Infrastructure

To modify infrastructure after initial deployment:

Edit Configuration

Modify terraform.tfvars or module files as needed

Plan Changes

tofu plan -out=tfplan

Review what will change

Apply Updates

tofu apply tfplan

Destroying Infrastructure

To remove all resources (use with caution):

# Plan destruction
tofu plan -destroy -out=destroy.tfplan

# Review what will be destroyed
tofu show destroy.tfplan

# Destroy resources
tofu apply destroy.tfplan

This will permanently delete: - S3 bucket and all MCP server data - Lambda function and logs - IAM roles and policies Backup S3 data before destroying!

Troubleshooting

Error: AccessDenied creating S3 bucket

Cause: Insufficient IAM permissionsSolution:

Verify AWS credentials are correct
Ensure IAM user has s3:CreateBucket permission
Check if bucket name is globally unique

Error: InvalidParameterValueException Lambda

Cause: Lambda payload too large or missingSolution:

# Re-package Lambda function
cd SuperBox-Infra/scripts
./package_lambda.sh  # or .ps1 for Windows

# Verify size (should be < 50MB)
ls -lh ../modules/lambda/lambda_payload.zip

Error: Region not supported

Cause: Invalid AWS region in configurationSolution:

Check aws_region in terraform.tfvars
Use valid region code (e.g., ap-south-1, us-east-1)
Verify region supports Lambda Function URLs

Next Steps

Configure Backend

Connect API server to deployed infrastructure

Monitoring Setup

Set up CloudWatch dashboards and alarms

Deploy CLI

Install and configure SuperBox CLI

Security Hardening

Apply security best practices

Getting Started

Core Concepts

Infrastructure

Backend

Frontend

REST API

Servers API

Auth API

CLI

CLI Commands

Prerequisites

Step 1: Get AWS Credentials

Step 2: Package Lambda Function

Step 3: Configure Variables

Step 4: Initialize Infrastructure

Step 5: Plan Deployment

Step 6: Deploy Infrastructure

Step 7: Retrieve Outputs

Step 8: Test Deployment

Configuration for Backend

Updating Infrastructure

Destroying Infrastructure

Troubleshooting

Next Steps

Configure Backend

Monitoring Setup

Deploy CLI

Security Hardening

Getting Started

Core Concepts

Infrastructure

Backend

Frontend

REST API

Servers API

Auth API

CLI

CLI Commands

​Prerequisites

​Step 1: Get AWS Credentials

​Step 2: Package Lambda Function

​Step 3: Configure Variables

​Step 4: Initialize Infrastructure

​Step 5: Plan Deployment

​Step 6: Deploy Infrastructure

​Step 7: Retrieve Outputs

​Step 8: Test Deployment

​Configuration for Backend

​Updating Infrastructure

​Destroying Infrastructure

​Troubleshooting

​Next Steps

Configure Backend

Monitoring Setup

Deploy CLI

Security Hardening

Prerequisites

Step 1: Get AWS Credentials

Step 2: Package Lambda Function

Step 3: Configure Variables

Step 4: Initialize Infrastructure

Step 5: Plan Deployment

Step 6: Deploy Infrastructure

Step 7: Retrieve Outputs

Step 8: Test Deployment

Configuration for Backend

Updating Infrastructure

Destroying Infrastructure

Troubleshooting

Next Steps