init

Author: linnjia-aws

Makefile

@@ -1,17 +1,301 @@
-## My Project
+# E2B on AWS Deployment Guide
 
-TODO: Fill this README out!
+## Introduction
 
-Be sure to:
+### Purpose
+
+E2B on AWS provides a secure, scalable, and customizable environment for running AI agent sandboxes in your own AWS account. This project addresses the growing need for organizations to maintain control over their AI infrastructure while leveraging the power of E2B's sandbox technology for AI agent development, testing, and deployment.
+
+This project is built based on version c746fd93d5f1260315c893dbd5d7290c0a41e52a (Mar 2), with newer versions still undergoing modifications. This E2B deployment can be used for testing purposes. If you encounter any issues, please contact the relevant team members or submit a PR directly. We would like to express our special thanks to all contributors involved in the project transformation.
+
+
+## Table of Contents
+- [Prerequisites](#prerequisites)
+- [Deployment Steps](#deployment-steps)
+  - [1. Setup EC2 Deployment Machine](#1-setup-ec2-deployment-machine)
+  - [2. Setup E2B Infrastructure](#2-setup-e2b-infrastructure)
+  - [3. Deploy Applications](#3-deploy-applications)
+  - [4. Setup Database](#4-setup-database)
+  - [5. Configure Grafana Monitoring](#5-configure-grafana-monitoring)
+  - [6. Test Sandbox SDK](#6-test-sandbox-sdk)
+- [Using E2B CLI](#using-e2b-cli)
+- [E2B SDK Cookbook](#e2b-sdk-cookbook)
+- [Troubleshooting](#troubleshooting)
+- [Appendix](#appendix)
+- [Architecture Diagram](#architecture-diagram)
+
+## Prerequisites
+- An AWS account with appropriate permissions
+- A domain name that you own
+
+Recommended for monitoring and logging
+- Grafana Account & Stack (see Step 15 for detailed notes)
+- Posthog Account
+
+> **Important Production Note:** When deploying to a production environment, ensure the following settings are enabled for security and reliability:
+> - `DB_INSTANCE_BACKUP_ENABLED`
+> - `RDS_AUTOMATIC_MINOR_VERSION_UPGRADE_ENABLED`
+> - `RDS_ENHANCED_MONITORING_ENABLED`
+> - `RDS_INSTANCE_LOGGING_ENABLED`
+> - `RDS_MULTI_AZ_SUPPORT`
+> - `S3_BUCKET_LOGGING_ENABLED`
+> - `EC2 Metadata service configuration`
+
+## Deployment Steps
+
+### 1. Setup EC2 Deployment Machine
+
+1. Download CloudFormation template: 
+2. In AWS CloudFormation service, use the downloaded YAML file:e2b-setup-env.yml
+   - In 'Domain Configuration', input a domain you own (e.g., `e2b.example.com`)
+   - Choose an existing EC2 key pair for SSH access (Session Manager is also supported)
+   - Complete all required fields and launch the CloudFormation stack
+3. Modify AllowRemoteSSHIPs(Note: For compliance and security reasons, we've restricted SSH access to a private IP range instead of allowing access from any IP address (10.0.0.0/0). This follows the principle of least privilege by limiting SSH access to your corporate network. Please adjust this value based on your specific network configuration.)
+4. Fill in the database information, paying attention to the password rules.
+5. After submitting the creation, refresh at the resources section.
+6. Go to Amazon Certificate Manager (ACM) to validate your domain:
+   - Click on your domain to find the required CNAME record for validation
+7. Add the CNAME record to your domain's DNS settings
+8. Wait for ACM domain validation (typically 5-10 minutes) until CloudFormation stack completes
+
+### 2. Setup E2B Infrastructure
+
+1. SSH into your deployment machine using your preferred SSH client or Session Manager
+2. Execute the following commands:
+
+```bashPackage all code, upload to S3, copy the code to the deployment machine created via CloudFormation, and switch to root
+sudo su root
+cd infra-iac/
+bash init.sh 
+more /opt/config.properties  # Confirm the environment exists
+
+cd packer
+bash packer.sh
+# If there's an error, try executing it one more time
+
+cd ../terraform
+bash start.sh
+# Wait until the terraform deployment completes
+```
+
+
+4. Configure DNS and scaling:
+   - Add a CNAME record for `*` with the value set to the DNS name of the automatically created ALB
+   - Set Auto Scaling groups for API instances to 1 or 2 (default is 0)
+   - Run `more /opt/config.properties | grep SECRET_NOMAD_ACL_TOKEN` to get the NOMAD token
+   - Access `nomad.<dns-yourself>` with the token to view the NOMAD dashboard
+
+### 3. Deploy Applications
+
+####  Configuration
+
+Several images are stored in the public registry. For production, it's recommended to build your own images and upload them to your ECR:
+   - Navigate to `~/infra/package` directory
+   - Run `bash build.sh`
+
+
+#### Deploy Nomad Applications
+
+```bash
+cd ../nomad 
+source nomad.sh
+bash ./prepare.sh 
+
+# Deploy all applications at once
+bash ./deploy.sh 
+
+
+# There are 10 applications in total
+```
+
+### 4. Setup Database
+
+```bash
+cd /opt/infra/e2b-infra-aws/infra-iac/db
+bash init-db.sh 
+
+# Save the following token information for later use:
+# User: xxx
+# Team ID: <ID>
+# Access Token: <e2b_token>
+# Team API Key: <e2b_API>
+```
+
+### 5. Configure Grafana Monitoring
+
+1. Login to https://grafana.com/ (register if needed)
+2. Access your settings page at https://grafana.com/orgs/<username>
+3. In your Stack, find 'Manage your stack' page
+4. Find 'OpenTelemetry' and click 'Configure'
+5. Note the following values from the dashboard:
+   ```
+   Endpoint for sending OTLP signals: xxxx
+   Instance ID: xxxxxxx
+   Password / API Token: xxxxx
+   ```
+
+6. Export NOMAD environment variables:
+```bash
+cat << EOF >> /opt/config.properties
+
+# Grafana configuration
+grafana_otel_collector_token=xxx
+grafana_otlp_url=xxx
+grafana_username=xxx
+EOF
+
+echo "Appended Grafana configuration to /opt/config.properties"
+```
+
+7. Deploy OpenTelemetry collector:
+```bash
+cd ~/e2b-on-aws/infra-iac/nomad
+bash ./deploy.sh otel-collector
+```
+
+8. Open Grafana Cloud Dashboard to view metrics, traces, and logs
+
+### 6. Test Sandbox SDK
+
+Test creation template（The script includes the following steps 1-6）
+```bash
+cd ~/e2b-on-aws/infra/infra-iac/nomad
+bash ./create_template.sh
+```
+
+1. In EC2 Auto Scaling Group, set the desired capacity of **e2b-0516-client** server to 1
+2. Create a sandbox template:
+
+```bash
+curl -X POST \
+ https://api.e2b.example.com/templates \
+ -H 'Authorization: <e2b_token>' \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "dockerfile": "FROM ubuntu:22.04\nRUN apt-get update && apt-get install -y python3\nCMD [\"python3\", \"-m\", \"http.server\", \"8080\"]",
+ "memoryMB": 4096,
+ "cpuCount": 4,
+ "startCommand": "echo $HOME"
+ }'
+```
+
+3. Save the response (note the buildID and templateID):
+```json
+{
+  "aliases": null,
+  "buildCount": 0,
+  "buildID": "<buildID>",
+  "cpuCount": 0,
+  "createdAt": "0001-01-01T00:00:00Z",
+  "createdBy": null,
+  "lastSpawnedAt": "0001-01-01T00:00:00Z",
+  "memoryMB": 0,
+  "public": false,
+  "spawnCount": 0,
+  "templateID": "<templateID>",
+  "updatedAt": "0001-01-01T00:00:00Z"
+}
+```
+
+4. Create ECR registry:
+```bash
+aws ecr get-login-password --region <AWS_REGION> | docker login --username AWS --password-stdin <AWS_acccount_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com
+aws ecr create-repository --repository-name e2bdev/base/<templateID> --region <AWS_REGION> || true
+```
+
+5. Pull and push the image:
+```bash
+docker pull e2bdev/base
+
+aws ecr get-login-password --region <AWS_REGION> | docker login --username AWS --password-stdin <AWS_acccount_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com
+docker tag e2bdev/base:latest <AWS_acccount_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com/e2bdev/base/<templateID>:<buildID>
+docker push <AWS_acccount_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com/e2bdev/base/<templateID>:<buildID>
+```
+
+6. Build RootFS:
+```bash
+curl -X POST \
+  https://api.e2b.example.com/templates/<templateID>/builds/<buildID> \
+  -H 'Authorization: <e2b_token>' \
+  -H 'Content-Type: application/json' 
+```
+
+7. Check API and Template Manager logs in Nomad Console for any issues
+8. Create a sandbox(Get the value of e2b_API to execute commands---  more ../infra-iac/db/config.json):
+```bash
+curl -X POST \
+ https://api.e2b.example.com/sandboxes \
+ -H "X-API-Key: <e2b_API>" \
+ -H 'Content-Type: application/json' \
+ -d '{
+        "templateID": "<template_ID>",
+        "timeout": 3600,
+        "autoPause": true,
+        "envVars": {
+        "EXAMPLE_VAR": "example_value"
+        },
+        "metadata": {
+            "purpose": "test"
+        }
+ }'
+```
+
+## Using E2B CLI
+
+```bash
+# Installation Guide: https://e2b.dev/docs/cli
+# For macOS
+brew install e2b
+
+# Export environment variables
+export E2B_API_KEY=xxx
+export E2B_ACCESS_TOKEN=xxx
+export E2B_DOMAIN="e2b.example.com"
+
+# Common E2B CLI commands
+# List all sandboxes
+e2b sandbox list
+ 
+# Connect to a sandbox
+e2b sandbox connect <sandbox-id>
+ 
+# Kill a sandbox
+e2b sandbox kill <sandbox-id>
+e2b sandbox kill --all
+```
+
+## E2B SDK Cookbook
+
+```bash
+git clone https://github.com/e2b-dev/e2b-cookbook.git
+cd e2b-cookbook/examples/hello-world-python
+poetry install
+
+# Edit .env file
+vim .env
+# Change E2B_API_KEY value
+
+poetry run start
+```
+
+## Troubleshooting
+
+1. **No nodes were eligible for evaluation error when deploying applications**
+   - Check node status and constraints
+
+2. **Driver Failure: Failed to pull from ECR**
+   - Error: `Failed to pull xxx.dkr.ecr.us-west-2.amazonaws.com/e2b-orchestration/api:latest: API error (404): pull access denied for xxx.dkr.ecr.us-west-2.amazonaws.com/e2b-orchestration/api, repository does not exist or may require 'docker login': denied: Your authorization token has expired. Reauthenticate and try again.`
+   - Solution: Execute `aws ecr get-login-password --region us-east-1` to get a new ECR token and update the HCL file
+
+3. For other unresolved issues, contact support
+
+## Appendix
 
-* Change the title in this README
-* Edit your repository description on GitHub
 
 ## Security
 
 See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.
 
 ## License
 
-This project is licensed under the Apache-2.0 License.
-
+This project is licensed under the Apache-2.0 License.