Skip to content

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.

The StackPort dashboard connected to AWS Emulator, with 51 of 51 services available and resource counts for EC2, IAM, S3, SQS, DynamoDB and more

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:

Terminal window
aws-emulator

By 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.

Terminal window
pip install stackport
AWS_ENDPOINT_URL=https://127.0.0.1:9297 stackport

Open 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.

The StackPort repository has a ready-made file that runs AWS Emulator, StackPort and a seed container together:

Terminal window
curl -O https://raw.githubusercontent.com/DaviReisVieira/stackport/main/examples/docker-compose.aws-emulator.yml
docker compose -f docker-compose.aws-emulator.yml up -d

Open 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 up builds 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, run docker compose -f docker-compose.aws-emulator.yml build --no-cache aws-emulator and 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 on https://127.0.0.1:9297, the address its certificate covers. That is also why both published ports, 127.0.0.1:8080 for StackPort and 127.0.0.1:9297 for the emulator, sit on the emulator’s service.
  • A volume holds the keys and certificate. The emulator writes them to the aws-emulator-files volume, which StackPort reads at /root/.aws/emulator. StackPort needs no AWS_ACCESS_KEY_ID or 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-recreate brings 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 before AWS_ACCESS_KEY_ID and AWS_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 need AWS_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 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:

Terminal window
unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILE
export AWS_SHARED_CREDENTIALS_FILE=~/.aws/emulator/9297/emulator_credentials
export AWS_CA_BUNDLE=~/.aws/emulator/9297/ca.pem
export AWS_DISABLE_HOST_PREFIX_INJECTION=true
The API Explorer's AWS CLI tab for SQS ListQueues, with a box titled 'AWS Emulator needs a little setup first' holding the unset and export lines above the aws sqs list-queues command

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):

Terminal window
mkdir -p ~/.aws/emulator
docker compose -f docker-compose.aws-emulator.yml cp aws-emulator:/home/emulator/.aws/emulator/9297 ~/.aws/emulator/
  • 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 with STACKPORT_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 uses us-east-1, the Region in the emulator’s own config file, unless you set AWS_REGION or 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 for 127.0.0.1. StackPort turns those prefixes off for every local endpoint, so the console and the API Explorer reach the emulator; the CLI needs AWS_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 off turns it off for a run, and the Compose file has a commented command: [ "--telemetry", "off" ] line for it. StackPort itself has no telemetry.
  • Switching emulators. Starting StackPort with a different AWS_ENDPOINT_URL points the default endpoint there for that run only. To keep several emulators at hand, give each one a name with STACKPORT_ENDPOINTS and switch from the top bar. See Saved endpoints.
  • Only probe what you use. Set STACKPORT_SERVICES to the services you need, for example STACKPORT_SERVICES=s3,sqs,dynamodb,lambda, to keep the dashboard focused.

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.