75 lines
3.6 KiB
Markdown
75 lines
3.6 KiB
Markdown
# 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:**
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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 |
|