EC2 Linux Instance as “Local” Caliper SDK Environment

The existing local setup docs assume a developer laptop (macOS/Windows/Linux desktop). This document maps those steps onto an EC2 Linux instance so a developer can treat the remote instance as their “local” environment — running Caliper Admin, the SDK, and q2 CLI directly on it, connecting back via SSH/VSCode Remote.

1. EC2 Instance Spec

Setting	Value	Rationale
AMI	Amazon Linux 2023 or Ubuntu 24.04 LTS	Both supported by Caliper Admin’s Linux installer
Instance type	`t3.medium` (2 vCPU, 4 GB RAM) minimum	Python venv build + Tornado server needs headroom beyond `t3.micro`
Storage	30 GB gp3 EBS	SDK repo + venv + dependencies
Key pair	Create or reuse an SSH key pair	Required for SSH access

2. Security Group (Network)

Inbound rules:

Port	Source	Purpose
22	Developer IP	SSH access

The SDK server (ports 1980/1981) does not need inbound rules — the local-dev-api handles connectivity via websocket. The running extension is accessed through https://local-dev-api.q2developer.com.

Outbound rules:

Destination	Purpose
`cdn.q2developer.com` (443)	Caliper Admin download
`q2developer.com` (443)	Authentication / API token
HQ URL (443)	SDK operations (`q2 install`, `q2 run`, etc.)
Sandbox SQL Server host (1433)	Database access

3. Base OS Setup

# Amazon Linux 2023
sudo dnf update -y
sudo dnf install -y git curl gcc openssl-devel bzip2-devel libffi-devel zlib-devel readline-devel sqlite-devel xz-devel

# Ubuntu 24.04
sudo apt update && sudo apt upgrade -y
sudo apt install -y git curl build-essential libssl-dev libbz2-dev libffi-dev zlib1g-dev libreadline-dev libsqlite3-dev liblzma-dev

Optional — Memcached (for local caching):

# Amazon Linux 2023
sudo dnf install -y memcached && sudo systemctl enable --now memcached

# Ubuntu
sudo apt install -y memcached && sudo systemctl enable --now memcached

4. Map to Local Setup Steps

Follow the standard local setup guide with these EC2-specific notes:

Step 1: API Token

No change — follow the docs.

Step 2: Caliper Admin

Run the Linux installer on the EC2 instance. Follow the Caliper Admin docs, using the Linux install path. Ensure ~/.local/bin is on PATH after installation.

Step 3: IDE Setup

VSCode Remote-SSH (recommended):

Install VSCode locally on your laptop
Use the Remote-SSH extension to connect to the EC2 instance
Then follow the IDE setup docs as normal — it works identically over Remote-SSH

Terminal-only alternative: SSH in, activate the venv, run q2 commands directly.

Step 4: Sandbox Database (optional)

No change — follow the docs. The SQL Server extension works over Remote-SSH.

Accessing the running extension

The extension does not need to be accessed directly on ports 1980/1981. Instead, it is available as an endpoint through https://local-dev-api.q2developer.com. Details in the running server (q2 run).

5. Environment Variables

Caliper Admin’s “Set Stack” command generates ~/.antilles/sdk_env_vars.sh with all required variables. See the configuration guide for the full reference.

6. Differences from True Local

Concern	Mitigation
No local browser	Extension accessed via `https://local-dev-api.q2developer.com`, not localhost
Instance cost	Use `t3.medium` spot instance or stop when idle; ~$0.04/hr on-demand
State persistence	EBS volume persists across stop/start; repo + venv survive reboots
SSH key management	Use AWS Session Manager as alternative to SSH key pairs
Multiple developers	Each developer gets their own instance (not shared like `sdk-shared-dev`)