Using StackPort with AWS Emulator
AWS Emulator is AWS’s local emulator of the AWS APIs. It serves every service on a single HTTPS port, 9297, and has no graphical interface of its own: you use it through the AWS CLI and the SDKs. StackPort gives it a web UI: a dashboard of every service with live resource counts, dedicated views for S3, DynamoDB, Lambda, SQS and more, and an API Explorer for every other operation.
StackPort talks to AWS Emulator over the standard AWS API, the same way the AWS CLI does. Nothing needs to be installed or enabled inside the emulator, and StackPort picks up the keys and certificate the emulator creates on every start by itself. StackPort is an independent open-source project, not made or endorsed by AWS.
1. Start AWS Emulator
Section titled “1. Start AWS Emulator”AWS publishes AWS Emulator as Linux packages (RPM and Debian, for x86_64 and Arm). On macOS and Windows you run it in a container built from a short Dockerfile, since there is no prebuilt image. Follow AWS’s guide for your system, Getting started on Linux or Getting started with Docker. With the Linux package installed, start it with:
aws-emulatorBy default it serves HTTPS on 127.0.0.1:9297, so only your own machine can reach it. Every time it starts, it writes a new certificate and a new pair of access keys to ~/.aws/emulator/9297/, and by default it only accepts requests signed with those keys.
AWS’s Docker command mounts ~/.aws/emulator into the container, so the files land in the same folder on your machine. On Linux, add --user "$(id -u):$(id -g)" to it as AWS’s guide says, so the files belong to you and StackPort can read them.
2. Start StackPort
Section titled “2. Start StackPort”pip install stackportAWS_ENDPOINT_URL=https://127.0.0.1:9297 stackportOpen http://localhost:8080. There are no credentials or certificate settings to pass: StackPort finds both in ~/.aws/emulator/9297/ (see How StackPort finds the keys and certificate). Use the address from AWS’s guide, https://127.0.0.1:9297: the emulator’s certificate only covers 127.0.0.1 and localhost.
To run StackPort in Docker too, use the Compose file below. A StackPort container can’t use host.docker.internal here, because the certificate doesn’t cover that name, so the Compose file puts StackPort on the emulator’s own network instead.
Docker Compose
Section titled “Docker Compose”The StackPort repository has a ready-made file that runs AWS Emulator, StackPort and a seed container together:
curl -O https://raw.githubusercontent.com/DaviReisVieira/stackport/main/examples/docker-compose.aws-emulator.ymldocker compose -f docker-compose.aws-emulator.yml up -dOpen http://localhost:8080. The seed creates a few resources across S3, SQS, SNS, DynamoDB, Secrets Manager, IAM, CloudWatch Logs and Step Functions, so the dashboard has something to show on first load. If it stays empty, check docker compose -f docker-compose.aws-emulator.yml logs seed.
examples/docker-compose.aws-emulator.yml is shaped around how AWS Emulator works:
- It builds the emulator image. The first
upbuilds one from the Dockerfile in AWS’s guide, with the package for your CPU (x86_64, or Arm such as Apple silicon). To move to a newer release, rundocker compose -f docker-compose.aws-emulator.yml build --no-cache aws-emulatorand start it again. - StackPort shares the emulator’s network. StackPort and the seed run with
network_mode: service:aws-emulator, so they reach the emulator onhttps://127.0.0.1:9297, the address its certificate covers. That is also why both published ports,127.0.0.1:8080for StackPort and127.0.0.1:9297for the emulator, sit on the emulator’s service. - A volume holds the keys and certificate. The emulator writes them to the
aws-emulator-filesvolume, which StackPort reads at/root/.aws/emulator. StackPort needs noAWS_ACCESS_KEY_IDor certificate settings, and follows the new ones after a restart. - Memory is capped at 2 GiB, as in AWS’s guide. Past that the container stops with exit code 137 and the emulated resources are gone.
docker compose -f docker-compose.aws-emulator.yml up -d --force-recreatebrings everything back.
It needs Docker Compose 2.17 or later with BuildKit, which is the default.
How StackPort finds the keys and certificate
Section titled “How StackPort finds the keys and certificate”For an endpoint at https://127.0.0.1:<port> or https://localhost:<port>, with the port written out, StackPort looks in ~/.aws/emulator/<port>/, the folder AWS Emulator writes for that port:
emulator_credentials: the keys StackPort signs requests with, when the endpoint uses the Default authentication type. They come beforeAWS_ACCESS_KEY_IDandAWS_SECRET_ACCESS_KEY, so test keys left in your shell don’t get in the way.ca.pem: the certificate StackPort trusts, for that endpoint only. StackPort doesn’t needAWS_CA_BUNDLE, which would replace the system certificates for every endpoint, real AWS included.
StackPort notices when those files change. After the emulator restarts with new keys and a new certificate, StackPort uses them without a restart of its own. An endpoint you give its own profile, keys or CA bundle in Settings uses those instead. If the emulator runs with --auth off, it writes no keys. StackPort then signs with AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY if you set them, and otherwise with placeholder keys, so it never reaches for your AWS profile.
STACKPORT_AWS_EMULATOR_DIR changes where StackPort looks (default ~/.aws/emulator), and an empty value turns the lookup off. See Environment Variables.
To check what StackPort used, edit the endpoint in Settings and press Test connection. It names the emulator it found, “Connected to AWS Emulator”, and shows which keys and certificate it used.
The AWS CLI next to StackPort
Section titled “The AWS CLI next to StackPort”The console needs none of this setup, but the AWS CLI does. When a guided lesson shows a CLI command, or the API Explorer shows a request as an AWS CLI command or boto3 code, StackPort adds the lines AWS Emulator needs, to run once in your terminal:
unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILEexport AWS_SHARED_CREDENTIALS_FILE=~/.aws/emulator/9297/emulator_credentialsexport AWS_CA_BUNDLE=~/.aws/emulator/9297/ca.pemexport AWS_DISABLE_HOST_PREFIX_INJECTION=true
These follow AWS’s guide, Pointing your AWS SDK at AWS Emulator: clear real credentials from the shell, sign with the emulator’s keys, trust its certificate, and stop the CLI from adding a prefix to the host name. StackPort only shows them when it uses the emulator’s own files for that endpoint.
When StackPort runs in a container, the lines use the paths on your machine, and a note explains how to copy the files out of the Compose volume (again after each restart):
mkdir -p ~/.aws/emulatordocker compose -f docker-compose.aws-emulator.yml cp aws-emulator:/home/emulator/.aws/emulator/9297 ~/.aws/emulator/What works
Section titled “What works”- The dashboard probes all 51 services StackPort knows about and names the emulator it is connected to. Services AWS Emulator implements show their resource counts; any it does not implement show as “Not supported”, and nothing else is affected. With AWS Emulator 1.0.367, all 51 answered.
- All 13 service views (S3, DynamoDB, Lambda, SQS, SNS, EC2, IAM, RDS, KMS, Step Functions, CloudWatch Logs, CloudWatch Metrics and Secrets Manager) use standard AWS API calls, so each one works as far as AWS Emulator implements the calls behind it. AWS publishes fidelity scores per service with each release.
- Write operations such as uploading to S3, editing DynamoDB items, sending SQS messages or starting Step Functions executions go straight to the emulator. S3 uploads of 8 MiB or more go up in 8 MiB parts, under the emulator’s 16 MiB limit per request.
- The API Explorer runs any operation against the emulator, including services StackPort has no view for, and copies it with the setup above.
- Guided lessons run against AWS Emulator like any local endpoint, and verify each step against its real state.
- The CLI finds the keys and certificate the same way:
stackport status --endpoint https://127.0.0.1:9297.
If a view behaves worse on AWS Emulator than on other emulators, please open an issue. That is exactly the kind of gap the project wants to close.
- A restart starts empty. The emulator keeps everything in memory and has no route to reset it, so restarting it is how you start over. Its keys and certificate change at the same time, and StackPort follows them by itself.
- Several emulators. Run each one on its own port (
aws-emulator -p 9300); each port gets its own folder of keys. Add each as an endpoint in StackPort, or name them withSTACKPORT_ENDPOINTS="emulator-a=https://127.0.0.1:9297,emulator-b=https://127.0.0.1:9300", and switch from the top bar. - One account, one Region. The emulator acts as a single account,
000000000000, and AWS’s guide suggests one Region per emulator. StackPort usesus-east-1, the Region in the emulator’s own config file, unless you setAWS_REGIONor a region on the endpoint. - Host prefixes. For a few operations, such as Cloud Map
DiscoverInstances, SDKs add a prefix to the host name, which doesn’t resolve for127.0.0.1. StackPort turns those prefixes off for every local endpoint, so the console and the API Explorer reach the emulator; the CLI needsAWS_DISABLE_HOST_PREFIX_INJECTION=true, which the setup above sets. - Telemetry. AWS Emulator sends usage data to AWS by default; its README explains what is collected.
aws-emulator --telemetry offturns it off for a run, and the Compose file has a commentedcommand: [ "--telemetry", "off" ]line for it. StackPort itself has no telemetry. - Switching emulators. Starting StackPort with a different
AWS_ENDPOINT_URLpoints thedefaultendpoint there for that run only. To keep several emulators at hand, give each one a name withSTACKPORT_ENDPOINTSand switch from the top bar. See Saved endpoints. - Only probe what you use. Set
STACKPORT_SERVICESto the services you need, for exampleSTACKPORT_SERVICES=s3,sqs,dynamodb,lambda, to keep the dashboard focused.
Related
Section titled “Related”- Emulators overview compares the setup for every supported emulator.
- Multiple Endpoints and Authentication covers per-endpoint keys and certificate settings.
- API Explorer calls any operation, with the AWS CLI setup above built in.
- Service Browsers lists what each view can do.
StackPort is an independent, open-source project (MIT). It is not affiliated with or endorsed by Amazon Web Services. MiniStack is its partner project; other emulator names belong to their own projects. AWS is a trademark of Amazon.com, Inc. or its affiliates.