# LocalStack Development Environment

> Local AWS development environment using LocalStack and Terraform

Develop and test AWS infrastructure locally without touching production. Fast, safe, and free.

## Features

- **Fast Iteration** - Changes deploy in seconds
- **Safe Testing** - Can't affect production resources
- **Cost Free** - No AWS charges
- **Offline Work** - Works without internet (after setup)
- **Parallel Development** - Each developer has their own instance

## Documentation

| Document | Description |
|----------|-------------|
| **[QUICKSTART.md](QUICKSTART.md)** | Get running in 5 minutes |
| **[INSTALLATION.md](INSTALLATION.md)** | Install prerequisites (Docker, Terraform, AWS CLI) |
| **[docs/WORKFLOWS.md](docs/WORKFLOWS.md)** | Common workflows and examples |
| **[docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)** | Solutions for common issues |
| **[docs/REFERENCE.md](docs/REFERENCE.md)** | Complete command & config reference |
| **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** | Technical details and design |

## Quick Start

```bash
# 1. Check prerequisites
make check

# 2. Create environment config
cp .env.shadow .env

# 3. Deploy everything
make deploy-all

# 4. Verify deployment
make verify
```

**Full instructions:** [QUICKSTART.md](QUICKSTART.md)

## Prerequisites

Required:
- Docker Desktop
- Terraform >= 1.11.0
- AWS CLI
- Make

**Installation guide:** [INSTALLATION.md](INSTALLATION.md)

## Project Structure

```
localstack/
├── terraform/              # Local Terraform configs (mirrored from terraform-infra)
│   ├── _shared/           # Shared provider overrides
│   ├── lambda-*/          # Lambda function projects
│   └── <your-project>/    # Your Terraform projects (S3, Step Functions, EventBridge, etc.)
├── scripts/               # Automation scripts
├── docs/                  # Detailed documentation
├── docker-compose.yaml    # LocalStack container config
└── Makefile              # Build and deployment commands
```

**Detailed architecture:** [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)

## Common Commands

```bash
# Deploy and manage
make deploy-all      # Deploy all projects in order
make up              # Start + deploy current project
make verify          # Show all deployed resources
make status          # Check service readiness

# Terraform operations
make tf-apply        # Deploy changes
make tf-plan         # Preview changes
make tf-destroy      # Destroy resources

# Manage LocalStack
make start           # Start LocalStack
make stop            # Stop LocalStack
make logs            # View logs
make clean           # Remove all data and state

# Utilities
make check           # Check prerequisites
make projects        # List available projects
make help            # Show all commands
```

**Complete reference:** [docs/REFERENCE.md](docs/REFERENCE.md)

## Quick Workflows

```bash
# Deploy & test
make deploy-all
make verify

# Make changes
vim terraform/${PROJECT}/main.tf
make tf-apply # PROJECT=<other-project>

# Fresh start
make clean && make deploy-all
```

**More:** [docs/WORKFLOWS.md](docs/WORKFLOWS.md)

## Troubleshooting

| Issue | Quick Fix |
|-------|-----------|
| LocalStack not responding | `make stop && make start` |
| Want fresh start | `make clean && make deploy-all` |
| Port 4566 in use | `lsof -i :4566` then `kill -9 <PID>` |
| Docker not running | Start Docker Desktop |

**Full troubleshooting guide:** [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)

## What's Deployed

Resources depend on your Terraform projects. All use `local-` prefix:
- Lambda functions
- S3 buckets
- Step Functions state machines
- EventBridge rules

Run `make verify` to see deployed resources. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for details.

## Scripts

- `check-prerequisites.sh` - Verify tools installed
- `awslocal.sh <cmd>` - AWS CLI with LocalStack endpoint
- `deploy-project.sh <name>` - Deploy single project
- `clean.sh` - Interactive cleanup

See [docs/REFERENCE.md](docs/REFERENCE.md) for details.

## Key Differences from Production

- Stub Lambdas, no external modules
- Simplified IAM, AES256 encryption
- Local state backend

See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for complete comparison.

## Learning Resources

- [LocalStack Documentation](https://docs.localstack.cloud/)
- [Terraform AWS Provider](https://registry.terraform.io/providers/hashicorp/aws/latest/docs)
- [AWS CLI with LocalStack](https://docs.localstack.cloud/user-guide/integrations/aws-cli/)

## Quick Reference

```bash
# Setup
cp .env.shadow .env && make deploy-all

# Daily use
make start && make tf-apply && make verify

# Debug
make logs

# Reset
make clean && make deploy-all
```

**Troubleshooting:** [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)

---

**Ready to start?** See [QUICKSTART.md](QUICKSTART.md)