3.6 KiB
Local Dev
SAM CLI, Lambda RIE, LocalStack, MinIO — when to reach for which.
The local dev problem
Lambda has no local runtime by default. Your only loop without tooling is: zip, upload, invoke, read CloudWatch logs, repeat — minutes per cycle. The tools below collapse that to seconds, with different trade-offs between fidelity, setup cost, and scope.
SAM CLI
What it is: AWS's official local Lambda emulator. Wraps Docker to run your function inside a container that matches the Lambda runtime environment exactly. Also emulates API Gateway.
Commands:
sam local invoke -e event.json # invoke once
sam local start-api # spin up local HTTP API gateway
sam local invoke --debug-port 5858 # attach debugger
Fidelity: high — same Amazon Linux image, same runtime, same filesystem layout. Catches architecture issues (x86 wheel on arm64) that a plain venv misses.
Downsides: requires Docker, slow to start (pulls image on first run), no MinIO/SQS/DynamoDB emulation built in. You wire those up separately.
Lambda Runtime Interface Emulator (RIE)
A lightweight binary embedded in all AWS-provided Lambda base images. When you run the image locally, RIE exposes a local HTTP endpoint that accepts invocations in the Lambda API format. You don't need SAM CLI — just Docker:
docker build -t my-fn .
docker run -p 9000:8080 my-fn
curl -XPOST http://localhost:9000/2015-03-31/functions/function/invocations \
-d '{"key": "value"}'
Use RIE when you're building container-image Lambdas and want to test them without SAM overhead.
LocalStack
A full AWS mock that emulates Lambda, S3, SQS, DynamoDB, API Gateway, and dozens more services in a single container. Community edition is free; Pro ($35/month) adds more services and persistent state.
When to use: integration tests that span multiple AWS services (e.g. an EventBridge rule that triggers a Lambda that writes to DynamoDB). Without LocalStack you'd need a real AWS account for these tests.
When to avoid: if you only need one service (just S3 → use MinIO; just Lambda → use SAM/RIE). LocalStack's Lambda emulation has occasional edge-case differences from the real runtime.
docker run --rm -p 4566:4566 localstack/localstack
AWS_DEFAULT_REGION=us-east-1 \
AWS_ACCESS_KEY_ID=test \
AWS_SECRET_ACCESS_KEY=test \
aws --endpoint-url=http://localhost:4566 s3 ls
MinIO (this project)
MinIO is an S3-compatible object store that runs locally in Docker. It implements the S3 API precisely enough that boto3/aioboto3 needs only an endpoint_url override to work against it. It is not a Lambda emulator — it replaces S3 only.
make up # starts MinIO on :9000 (API) and :9001 (console)
SOURCE_DIR=~/pdfs make seed # uploads PDFs to MinIO
make invoke # runs lambda_function.py against MinIO via invoke.py
This is the lightest possible local setup: no Docker-in-Docker, no SAM overhead, minimal latency. The function handler runs in your local Python process against a real S3-compatible store. Differences from real Lambda (no execution environment lifecycle, no /tmp isolation between runs) are acceptable for the development loop but not for environment-fidelity tests.
Decision matrix
| Need | Reach for |
|---|---|
| Fast iteration on handler logic | MinIO + python invoke.py (this project's setup) |
| Emulate Lambda runtime + API Gateway locally | SAM CLI |
| Test a container-image Lambda | Lambda RIE via Docker |
| Integration test across multiple AWS services | LocalStack |
| Full-fidelity staging before prod | Real AWS account, separate environment |