# 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 |