Skip to Content
Cloud Engineering Academy
0. Orientation & a Safe Learning Environment

Zero-cost local practice

Practise AWS APIs on your own PC with AWS Emulator, LocalStack, DynamoDB Local, SAM local, Testcontainers and docker compose — and know exactly what local emulation cannot prove.

beginner⏱ 1 h 🟢 FreeDVA-C03

Assumes: .NET 10 LTS · AWS SDK for .NET v4 · AWS CLI v2 · Testcontainers for .NET 4.17 · DynamoDB Local 3.3.2 · Region us-east-1. Verified against official sources on 2026-11-17.

Learning objectives

By the end of this lesson you can:

  • Explain what AWS Emulator is, run it on Windows in a container, and point the AWS CLI and SDK at it safely.
  • Describe the current LocalStack offer (free Hobby plan for non-commercial use, auth token required) and when it is worth using.
  • Run DynamoDB Local with docker compose and from an xUnit test with Testcontainers for .NET.
  • Use SAM local to run a Lambda function on your PC.
  • State clearly what local emulation can and cannot prove before you trust a green test.

Prerequisites

  • Tooling setup on Windows — a working container runtime (Docker Desktop, Podman or Rancher Desktop) and AWS CLI v2.
  • No AWS account is needed for anything in this lesson.

Why this matters in banking

Banks run thousands of automated tests on every change, and most of them cannot touch a real AWS account: pipelines run in isolated networks, test accounts cost money, and test data must never be real. Local emulators let you test the code that calls AWS quickly and for free. The danger is over-trusting them: a test that passes against an emulator says nothing about whether the IAM policy, the KMS key policy or the VPC routing will let the real call through. Many production AccessDenied incidents come from code that was "fully tested" locally.

The idea in plain language

An emulator is a program on your PC that pretends to be AWS. It listens on a local port and answers API calls with the same shapes AWS uses. You point your SDK at it instead of at AWS, and your code cannot tell the difference — for the parts the emulator implements.

Analogy: An emulator is the bank's training till. It looks and beeps like the real one, so tellers can practise transactions without moving money. But it is not connected to the core banking system, the fraud rules or the vault time-lock — passing on the training till does not prove the real transaction would clear.

What problem each option solves

OptionWhat it isCost and licence (checked 2026-11-17)Best forLimits
AWS Emulator (aws/aws-emulator)AWS's own local emulator of AWS APIs, launched 2026-11-11Free, no service fee; CC0-1.0 (the vendor/ folder is Apache-2.0); telemetry on by default, can be turned offBroad API coverage for SDK/CLI tests; services with a published API modelDoes not evaluate IAM or resource policies like AWS; one account (000000000000) and one Region per instance; in-memory only; fidelity varies by service
LocalStackCommercial emulator; Community edition no longer updatedHobby plan free for non-commercial use, needs an account and auth token since 2026-03-23; paid plans from USD 39/month (annual)Mature integrations, Testcontainers moduleHobby: 30+ services, no persistence, no IAM enforcement; several services (for example ECS, RDS, Cognito, Glue, Athena) are not in Hobby per our research notes
DynamoDB LocalAWS's downloadable DynamoDBFreeDynamoDB data-access code and testsDynamoDB only; no IAM; performance not representative
SAM localRuns Lambda functions and API Gateway locally in containersFree (SAM CLI is open source)Debugging Lambda handlers and event payloadsYour function's calls to other AWS services still go to real AWS unless you redirect them
Testcontainers for .NETLibrary that starts containers from xUnit testsFree (MIT)Repeatable integration tests with clean state per test classNeeds a container runtime on every machine and CI agent
docker composeRuns several containers togetherFree with your runtimeA local stack: API + DynamoDB Local + emulatorStill an emulation of AWS, not AWS

Microsoft / Azure comparison

You know (Microsoft/Azure)AWS equivalentWhat's different
Azurite (Storage emulator)AWS Emulator / LocalStack for S3AWS Emulator covers many services on one endpoint, not just storage
Azure Cosmos DB emulatorDynamoDB LocalDynamoDB Local is a small Java app; also available as a container
Azure Functions Core Tools func startsam local start-api / sam local invokeSAM runs your function inside a Lambda-like container image
Testcontainers with SQL Server / AzuriteTestcontainers.DynamoDb, Testcontainers.LocalStackSame library family, same xUnit patterns
Connecting to emulators via connection stringsAWS_ENDPOINT_URL or ServiceURL in client configThe SDK for .NET v4 reads AWS_ENDPOINT_URL and AWS_ENDPOINT_URL_<SERVICE>

Architecture

Security-boundary view: the dashed line is the risk. If the endpoint variable is missing in the shell or CI job, the same code calls real AWS with whatever credentials it finds. Always unset real credentials before running emulator tests, and bind emulator ports to 127.0.0.1 only so other machines on your network cannot reach them.

Step-by-step implementation

Run AWS Emulator in a container (Windows)

AWS does not publish a prebuilt image; you build one from the Dockerfile in the Docker getting-started guide. Create an empty folder with this Dockerfile (x86_64):

Dockerfile
FROM public.ecr.aws/amazonlinux/amazonlinux:2023-minimal
ADD https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator-x86_64.rpm /tmp/aws-emulator.rpm
RUN rpm -i /tmp/aws-emulator.rpm && rm /tmp/aws-emulator.rpm \
    && mkdir -p /home/emulator && chown 1000 /home/emulator
USER 1000
ENV HOME=/home/emulator
EXPOSE 9297
ENTRYPOINT ["aws-emulator", "-b", "0.0.0.0"]

Build and run it in PowerShell. 127.0.0.1: in the port mapping keeps it private to your PC; the volume shares the generated credentials and certificate with Windows.

docker build -t aws-emulator .
New-Item -ItemType Directory -Force "$env:USERPROFILE\.aws\emulator"

$port = 9297
docker run --rm --memory=2g --memory-swap=2g -p "127.0.0.1:${port}:${port}" `
  -v "$env:USERPROFILE\.aws\emulator:/home/emulator/.aws/emulator" `
  aws-emulator -p $port --telemetry off

On start it creates a fresh access key, a config file and a certificate (ca.pem) under %USERPROFILE%\.aws\emulator\9297\. Those keys only work with that run of the emulator.

Point the AWS CLI at the emulator

In a second terminal:

# Send every AWS call from this shell to the emulator.
$env:AWS_ENDPOINT_URL = "https://127.0.0.1:9297"
$env:AWS_SHARED_CREDENTIALS_FILE = "$env:USERPROFILE\.aws\emulator\9297\emulator_credentials"
$env:AWS_CONFIG_FILE = "$env:USERPROFILE\.aws\emulator\9297\config"
$env:AWS_CA_BUNDLE = "$env:USERPROFILE\.aws\emulator\9297\ca.pem"
$env:AWS_EC2_METADATA_DISABLED = "true"
$env:AWS_DISABLE_HOST_PREFIX_INJECTION = "true"
$env:AWS_REGION = "us-east-1"
$env:AWS_DEFAULT_REGION = "us-east-1"

# Make sure no real credentials can leak into this shell.
Remove-Item Env:AWS_ACCESS_KEY_ID, Env:AWS_SECRET_ACCESS_KEY, Env:AWS_SESSION_TOKEN, Env:AWS_PROFILE -ErrorAction SilentlyContinue

# Proof you are talking to the emulator: Account must be 000000000000.
aws sts get-caller-identity

You should see "Account": "000000000000" and "Arn": "arn:aws:iam::000000000000:user/emulator". If you see your real account ID, stop — your requests are going to AWS.

Create something and read it back

aws s3api create-bucket --bucket cea-local-statements
aws s3api list-buckets --query "Buckets[].Name"
aws dynamodb create-table --table-name accounts `
  --attribute-definitions AttributeName=accountId,AttributeType=S `
  --key-schema AttributeName=accountId,KeyType=HASH --billing-mode PAY_PER_REQUEST

Stop the emulator with Ctrl+C: every resource disappears, because state is kept in memory. That is a feature for tests — each run starts clean.

Use the emulator from .NET

The AWS SDK for .NET v4 reads AWS_ENDPOINT_URL, so most code needs no change. Two Windows-specific points:

  • Trusting the certificate. The emulator's guide says the .NET SDK uses SSL_CERT_FILE pointing at ca.pem — that applies to .NET on Linux (for example inside WSL or a dev container). On Windows, .NET uses the Windows certificate store, and the guide notes you might need to import ca.pem there ⚠ VERIFY. The certificate is regenerated on every start, so the simplest reliable option is to run emulator tests from WSL or a Linux container with SSL_CERT_FILE set.
  • S3 addressing. The emulator only accepts bucket names in the URL path. Set ForcePathStyle = true on AmazonS3Config when testing S3 against it.

The verify-setup lab recognises the emulator: it prints an [INFO] line when the account is 000000000000.

Run DynamoDB Local with docker compose

compose.yaml
services:
  dynamodb-local:
    image: amazon/dynamodb-local:3.3.2
    command: "-jar DynamoDBLocal.jar -sharedDb -inMemory"
    ports:
      - "127.0.0.1:8000:8000"
docker compose up -d
# DynamoDB Local accepts any credentials; pass the endpoint explicitly.
aws dynamodb list-tables --endpoint-url http://localhost:8000 --region us-east-1
docker compose down

If the CLI complains about missing credentials here, run it in the emulator shell from step 2 or set dummy values just for that shell ($env:AWS_ACCESS_KEY_ID="local"; $env:AWS_SECRET_ACCESS_KEY="local") — they are placeholders for a local tool, never real keys.

Test with Testcontainers for .NET

Add Testcontainers.DynamoDb (4.17.0) and AWSSDK.DynamoDBv2 to an xUnit v3 test project. The complete code below starts DynamoDB Local per test class and throws it away afterwards.

Try SAM local

SAM CLI release notes list dotnet10 runtime support from version 1.151.0; you installed 1.172 or later. In a SAM project folder:

sam build
sam local invoke HelloFunction --event events/event.json
sam local start-api      # serves API Gateway routes on http://127.0.0.1:3000

Module 3 builds a real .NET Lambda function; here it is enough to know the commands exist and need a container runtime.

Optional: LocalStack Hobby

Create a free LocalStack account, copy your auth token, and keep it out of source control:

$env:LOCALSTACK_AUTH_TOKEN = "<paste your token in this shell only>"
docker run --rm -p 127.0.0.1:4566:4566 -e LOCALSTACK_AUTH_TOKEN=$env:LOCALSTACK_AUTH_TOKEN localstack/localstack

The Hobby plan is for non-commercial use: fine for personal study, not for your bank's projects. The legacy Community image can be pinned to an old version, but it receives no updates or security patches — avoid it.

What local emulation can and cannot prove

QuestionLocal emulationWhy
Does my code build requests correctly and handle responses (serialisation, pagination, null collections in SDK v4)?✅ Can proveRequest/response shapes come from the same API models
Does my code handle validation errors (bad table name, missing key)?✅ MostlyAWS Emulator aims to return the same errors as AWS for implemented operations
Does my business logic work end-to-end across two or three services?⚠️ PartlyCross-service behaviour (events, triggers) varies by tool and service
Will IAM allow it — identity policies, resource policies, SCPs, permission boundaries, KMS key policies?❌ Cannot proveAWS Emulator does not evaluate policies the way AWS does; LocalStack Hobby does not enforce IAM
Will the network allow it — VPC routes, security groups, NACLs, VPC endpoints, private DNS, NAT?❌ Cannot proveLocal containers have no VPC; everything is reachable on localhost
Will it work at production scale — quotas, throttling, burst limits, partition hot-spots?❌ Cannot proveEmulators do not apply AWS service quotas or throttling realistically
Is it fast enough — latency, cold starts, connection reuse?❌ Cannot proveYour laptop's timings say nothing about cross-AZ calls or Lambda cold starts
How does the managed service behave — Multi-AZ failover, backups, maintenance, eventual consistency timing, scaling events?❌ Cannot proveThese are operational behaviours of AWS infrastructure, not API responses
Will it work across accounts or Regions?❌ Cannot proveAWS Emulator keeps one account and does not separate Regions per instance
Does my IaC deploy cleanly?⚠️ PartlyFidelity for CloudFormation, CDK and Terraform varies; always deploy to the sandbox before trusting it
What will it cost?❌ Cannot proveEmulators are free; use the pricing pages and Cost Explorer

Rule of thumb: emulators prove your code; only a real sandbox account proves the cloud configuration. Banks usually run fast emulator tests on every commit and a smaller set of tests against a real non-production account before release.

AWS Console instructions

Not applicable — local practice uses no AWS account. When you later need proof that only real AWS can give (IAM, networking), use your sandbox account and the teardown checklist.

AWS CLI

The key pattern is redirecting the CLI without touching your real profiles:

# One-off: a single command to DynamoDB Local.
aws dynamodb list-tables --endpoint-url http://localhost:8000 --region us-east-1

# Whole shell to AWS Emulator (see step 2), and a clean exit afterwards:
Remove-Item Env:AWS_ENDPOINT_URL, Env:AWS_SHARED_CREDENTIALS_FILE, Env:AWS_CONFIG_FILE, Env:AWS_CA_BUNDLE, Env:AWS_DISABLE_HOST_PREFIX_INJECTION -ErrorAction SilentlyContinue

# Check the emulator is ready (returns "ok").
curl.exe --cacert "$env:USERPROFILE\.aws\emulator\9297\ca.pem" https://127.0.0.1:9297/__admin/health

AWS_DISABLE_HOST_PREFIX_INJECTION must only be set in emulator shells — against real AWS it breaks operations that rely on host prefixes.

Infrastructure as Code

Not covered here. AWS Emulator's own documentation says IaC fidelity varies by service; Module 10 deploys IaC to the real sandbox account, which is the only reliable test.

Complete code

An xUnit v3 integration test that runs DynamoDB Local in a container (compiled against Testcontainers.DynamoDb 4.17.0 and AWSSDK.DynamoDBv2 4.0 on 2026-11-17):

AccountsTableTests.cs
using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.Model;
using Amazon.Runtime;
using Testcontainers.DynamoDb;

namespace Cea.Labs.LocalPractice.Tests;

public sealed class AccountsTableTests : IAsyncLifetime
{
    // Starts amazon/dynamodb-local in a container for this test class.
    private readonly DynamoDbContainer _dynamo = new DynamoDbBuilder("amazon/dynamodb-local:3.3.2").Build();

    public async ValueTask InitializeAsync() => await _dynamo.StartAsync();

    public async ValueTask DisposeAsync() => await _dynamo.DisposeAsync();

    [Fact]
    public async Task Can_store_and_read_a_fictional_account()
    {
        // DynamoDB Local accepts any credentials; these are placeholders, not real keys.
        var config = new AmazonDynamoDBConfig
        {
            ServiceURL = _dynamo.GetConnectionString(),
            AuthenticationRegion = "us-east-1",
        };
        using var client = new AmazonDynamoDBClient(new BasicAWSCredentials("local", "local"), config);

        // Lets the test runner cancel AWS calls if the run is aborted.
        var ct = TestContext.Current.CancellationToken;

        await client.CreateTableAsync(new CreateTableRequest
        {
            TableName = "accounts",
            BillingMode = BillingMode.PAY_PER_REQUEST,
            AttributeDefinitions = [new AttributeDefinition("accountId", ScalarAttributeType.S)],
            KeySchema = [new KeySchemaElement("accountId", KeyType.HASH)],
        }, ct);

        await client.PutItemAsync("accounts", new Dictionary<string, AttributeValue>
        {
            ["accountId"] = new AttributeValue { S = "ACC-0001" },
            ["holder"] = new AttributeValue { S = "Test Customer One" },
        }, ct);

        var item = await client.GetItemAsync("accounts", new Dictionary<string, AttributeValue>
        {
            ["accountId"] = new AttributeValue { S = "ACC-0001" },
        }, ct);

        Assert.Equal("Test Customer One", item.Item["holder"].S);
    }
}

Code explained line by line

  1. using Testcontainers.DynamoDb; — the Testcontainers module that knows how to start and wait for DynamoDB Local.
  2. IAsyncLifetime — xUnit v3's hook for async setup/teardown; note it uses ValueTask.
  3. new DynamoDbBuilder("amazon/dynamodb-local:3.3.2").Build() — pins the image version so tests are repeatable.
  4. InitializeAsync / DisposeAsync — start the container before the tests in the class and remove it afterwards, so no state leaks between runs.
  5. ServiceURL = _dynamo.GetConnectionString() — the container's mapped http:// address; this overrides the AWS endpoint for this client only.
  6. AuthenticationRegion = "us-east-1" — the Region used for request signing when a custom endpoint is set.
  7. new BasicAWSCredentials("local", "local") — dummy credentials; DynamoDB Local does not check them. Never put real keys in tests.
  8. TestContext.Current.CancellationToken — xUnit v3's token; passing it to SDK calls lets an aborted run stop promptly (the xUnit analyzer requires it).
  9. BillingMode.PAY_PER_REQUEST — on-demand mode, so no capacity settings are needed.
  10. CreateTableAsync / PutItemAsync / GetItemAsync — the same API calls you would make against real DynamoDB.
  11. Assert.Equal(...) — proves the round trip works. It does not prove IAM would allow it in AWS.

The project file needs xunit.v3, AWSSDK.DynamoDBv2 and Testcontainers.DynamoDb, with OutputType set to Exe like the course's other test projects.

Security considerations

  • Bind every emulator port to 127.0.0.1. The AWS Emulator guide warns that -p 9297:9297 (without the address) exposes it to your whole network.
  • Do not use emulators to test security controls. AWS Emulator's documentation says so explicitly.
  • Keep real credentials out of emulator shells and CI jobs, and set AWS_EC2_METADATA_DISABLED=true so the SDK cannot fall back to instance credentials on a build server.
  • Treat your LocalStack auth token like a password: environment variable or secret store, never in Git.
  • Turn off AWS Emulator telemetry if your organisation requires it (--telemetry off, EMULATOR_TELEMETRY=off or config.toml).

⚠ Learning shortcut — not for production

Dummy credentials like local/local and disabled certificate checks are acceptable only for local emulators. In a bank's CI, integration tests that need AWS run against a dedicated non-production account using short-lived OIDC credentials, with real IAM policies in place, so the tests also prove the permissions.

Banking use case

"Harbour Bank" (fictional) builds a statement-export service that writes PDF statements to S3 and metadata to DynamoDB. Developers run unit tests and Testcontainers-based DynamoDB tests on every commit in under two minutes, with generated fictional customers. A nightly pipeline deploys the service to a non-production AWS account and runs a smaller suite that proves the task role can write only to its own bucket prefix, that the KMS key policy allows encryption, and that the service reaches DynamoDB through a VPC endpoint. That second suite has caught several AccessDenied errors the emulator tests could never have found.

Common mistakes

  • Treating a green emulator test as proof the cloud setup works → emulators don't evaluate IAM or networking → add a real-account test stage.
  • Forgetting the endpoint variable in one shell → code silently calls real AWS → print the caller identity at the start of every emulator test run.
  • Exposing emulator ports to the network → -p 9297:9297 binds all interfaces → always prefix 127.0.0.1:.
  • Using localhost instead of 127.0.0.1 for AWS Emulator S3 tests → some SDKs then put the bucket in the host name, which the emulator rejects → keep 127.0.0.1.
  • Pinning the old LocalStack Community image → it looks free forever → it gets no security fixes.
  • Using LocalStack Hobby for work projects → it's "free" → the Hobby terms are non-commercial.

Troubleshooting

SymptomLikely causeFix
get-caller-identity shows your real accountEndpoint variable missing, or real credentials in the environmentRe-run the step 2 variables; unset AWS_PROFILE and key variables
SSL / certificate errors from the CLIAWS_CA_BUNDLE not set or emulator restarted (new certificate)Point AWS_CA_BUNDLE at the current ca.pem
.NET throws a TLS trust error against AWS Emulator on WindowsWindows does not trust the emulator's certificateRun the test from WSL/Linux with SSL_CERT_FILE, or import the current ca.pem into the user certificate store ⚠ VERIFY
HTTP 501 NotImplementedOperation not implemented in AWS Emulator yetCheck the fidelity scores on the releases page; use another tool or real AWS
Container exits with code 137Emulator exceeded the 2 GiB memory limitUse fewer resources or raise --memory
LocalStack exits immediately with a licence errorMissing or invalid LOCALSTACK_AUTH_TOKENSet the token in the shell; check your plan
Testcontainers cannot find DockerRuntime not running, or Podman socket not exposedStart the runtime; for Podman enable the Docker-compatible API

Cost and cleanup

Cost: USD 0 — nothing runs in AWS. Local containers use disk and memory only.

# Stop containers and remove images you no longer need.
docker compose down
docker image rm aws-emulator amazon/dynamodb-local:3.3.2
# Optional: delete the emulator's local files (credentials, certificate, config).
Remove-Item -Recurse -Force "$env:USERPROFILE\.aws\emulator"

Close every emulator shell so no AWS_ENDPOINT_URL or AWS_CA_BUNDLE variable survives into your next AWS session.

Exercises

  • 🟢 Guided: Run AWS Emulator, create a bucket and a DynamoDB table with the CLI, confirm get-caller-identity shows 000000000000, then stop it and confirm everything is gone after a restart.
  • 🟡 Challenge: Create the xUnit v3 project from the complete code, add a second test that writes 25 fictional accounts and reads them back with a Scan, and run it with dotnet test. Then make the same test run against AWS Emulator instead of DynamoDB Local using only environment variables.
  • 🔴 Live problem: A teammate's integration tests pass locally against LocalStack, but the deployed service fails with AccessDeniedException on dynamodb:PutItem. They say "the tests prove the code is fine, so AWS is broken." Write the reply you would post in the team channel.

Assignment

Add a local/ folder to your learning-journal repository with the compose.yaml, a README.md explaining how to start and stop each tool, and the "can / cannot prove" table rewritten in your own words for the services you expect to use at work.

Solutions

Knowledge check

Interview questions

  • "How do you test code that depends on AWS services?" — Unit tests with interfaces and fakes; integration tests against emulators or Testcontainers for fast feedback; and a smaller suite against a real non-production account that proves IAM, networking and encryption, run in the pipeline with short-lived credentials.
  • "What are the limits of LocalStack-style emulators?" — They don't reproduce IAM evaluation, VPC networking, quotas, latency or managed-service operations, and fidelity varies by service and version.

Certification practice

Completion checklist

  • AWS Emulator runs in a container bound to 127.0.0.1, and get-caller-identity shows 000000000000
  • DynamoDB Local runs with docker compose
  • I can explain at least five things local emulation cannot prove
  • My emulator shells are closed and no endpoint variables remain

Key takeaways

  • AWS Emulator (launched 2026-11-11) is free, CC0-licensed and broad; it runs on Windows through a container you build yourself.
  • LocalStack's free Hobby plan needs an auth token and is for non-commercial use only.
  • DynamoDB Local + Testcontainers gives fast, repeatable .NET integration tests.
  • Emulators prove your code, not your cloud configuration — IAM, networking, quotas, latency and managed-service behaviour need a real account.
  • Always confirm where your calls are going; a missing endpoint variable means real AWS.

Further reading

Independent learning resource — not affiliated with, endorsed or sponsored by Amazon Web Services. AWS and related marks are trademarks of Amazon.com, Inc. or its affiliates. All banking data in examples is fictional. Sample architectures are for learning and are not automatically compliant with GDPR, PCI DSS or any banking regulation.

On this page