CLI walkthrough

Progress checklist

Know the reading order
Know the demo.sh subcommands

Overview

Work the pages in order. Each page shows the AWS CLI first, then the matching scripts/demo.sh subcommand. The script echoes every command before it runs — it teaches, it does not hide.

Reading order

Install tooling — AWS CLI ≥ 2.15.0 (latest fine)
Prerequisites — account, profile, Region, Express AZ
Architecture — what you are building
Then the walkthrough pages below

1. Build harness image

2. Create the VPC

3. Create the buckets

4. IAM and EC2

5. Seed and run harness

6. Read the dashboard

7. Tear down

After: Where Express fits

Lab suffix (`LAB_SUFFIX`)

Every resource name includes a short unique suffix so down only touches this lab run.

Item	Value
Env var	`LAB_SUFFIX`
Used in names	`s3x-hotlookup-${LAB_SUFFIX}-…`, directory bucket `s3x-hotlookup-${LAB_SUFFIX}--apse2-az1--x-s3`
If unset for `demo.sh up`	Auto-set to `$(date +%Y%m%d%H%M%S)` and stored in `.lab-state.json`
Manual CLI pages	You must export it yourself before copying commands

export AWS_PROFILE=sandbox
export AWS_REGION=ap-southeast-2
# pick one durable value for this run, or generate:
export LAB_SUFFIX=$(date +%Y%m%d%H%M%S)
# example result: 20260920105100

In code samples, $LAB_SUFFIX is that value — not the literal string SUFFIX.

`demo.sh` cheat sheet

export AWS_PROFILE=sandbox
export AWS_REGION=ap-southeast-2
# optional — omit to let up generate one:
# export LAB_SUFFIX=$(date +%Y%m%d%H%M%S)

./scripts/image.sh up        # once: ECR + CodeBuild (durable)
./scripts/image.sh build     # push s3x-hotlookup-harness:tag
./scripts/demo.sh up         # VPC, endpoints, buckets, IAM, EC2 (pulls image)
./scripts/demo.sh status     # read-only
./scripts/demo.sh seed       # put bakeoff keys into both buckets
./scripts/demo.sh harness    # how to rebuild image / re-pull
./scripts/demo.sh dash       # print public dashboard URL (:8080)
./scripts/demo.sh port-forward  # SSM tunnel → http://127.0.0.1:8080/
./scripts/demo.sh down       # type LAB_SUFFIX — lab resources
./scripts/image.sh down      # type s3x-hotlookup-harness — remove everything else

Subcommand	Mutates?	Notes
`image.sh up`	yes	Durable ECR + CodeBuild; not removed by `demo.sh down`
`image.sh build`	yes	CodeBuild → ECR push
`demo.sh up`	yes	Sets `LAB_SUFFIX` if missing; pulls harness from ECR; writes `.lab-state.json`
`demo.sh status`	no	Safe any time
`demo.sh seed`	yes	Writes identical hot keys to Express + Standard
`demo.sh harness`	no	Prints rebuild / re-pull guidance
`demo.sh dash`	no	Prints the public dashboard URL on port 8080
`demo.sh port-forward`	no	SSM port-forward to `http://127.0.0.1:8080/` (needs Session Manager plugin)
`demo.sh down`	yes	Confirms by typing the stored `LAB_SUFFIX` (lab only)
`image.sh down`	yes	Confirms by typing `s3x-hotlookup-harness` — required to remove everything

Conventions

Convention	Value
Profile	`AWS_PROFILE=sandbox`
Suffix	`LAB_SUFFIX` (timestamp or your choice)
Name prefix	`s3x-hotlookup-${LAB_SUFFIX}-…`
Tag	`Project=s3-express-hot-lookup-walkthrough`
Default Region	`ap-southeast-2`
Express AZ ID	`apse2-az1`
AWS CLI	Minimum 2.15.0 (latest v2 recommended)
Mutation guard	`S3X_LAB_ALLOW_AWS=1`
Local artifacts	`.lab/` (gitignored)
Lab state	`.lab-state.json` (gitignored) — written by `demo.sh`
Image state	`.image-state.json` (gitignored) — written by `image.sh`
ECR repo	`s3x-hotlookup-harness`