# Installation Guide

**Last updated:** 2025-11-22

Installation instructions for LocalStack prerequisites.

## Required Tools

| Tool | Purpose | Check |
|------|---------|-------|
| Docker Desktop | Run LocalStack | `docker --version` |
| Terraform | Deploy infrastructure | `terraform --version` |
| AWS CLI | Interact with LocalStack | `aws --version` |

## Optional Tools

| Tool | Purpose | Install |
|------|---------|---------|
| tflocal | Easier Terraform commands | `pip3 install terraform-local` |
| jq | Parse JSON output | `brew install jq` |

## Quick Install (macOS)

```bash
# Install Homebrew (if needed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install everything
brew install --cask docker
brew tap hashicorp/tap
brew install hashicorp/tap/terraform awscli terraform-local jq

# Start Docker
open -a Docker
```

## Manual Install

### Docker Desktop

**macOS:** `brew install --cask docker` or download from https://www.docker.com/products/docker-desktop/
**Linux:** `sudo apt-get install docker.io docker-compose`
**Windows:** Download from https://www.docker.com/products/docker-desktop/

### Terraform

**macOS:** `brew install hashicorp/tap/terraform`
**Linux:**
```bash
wget -O- https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt update && sudo apt install terraform
```

**Windows:** `choco install terraform`

### AWS CLI

**macOS:** `brew install awscli`
**Linux:**
```bash
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install
```

**Windows:** Download from https://awscli.amazonaws.com/AWSCLIV2.msi

## Verify Installation

```bash
# Run this in the localstack directory
make check
```

Or manually:
```bash
docker --version          # 20.10+
terraform --version       # 1.0+
aws --version            # 2.0+
docker ps                # Should work without errors
```

## Docker Configuration

**Recommended resources:**
- CPUs: 4+
- Memory: 8GB+
- Disk: 60GB+

Configure in: Docker Desktop → Settings → Resources

## Troubleshooting

**Docker: "Permission denied" (Linux)**
```bash
sudo usermod -aG docker $USER
newgrp docker
```

**Command not found**
```bash
# Add to ~/.zshrc or ~/.bashrc
export PATH="/usr/local/bin:$PATH"
export PATH="$(python3 -m site --user-base)/bin:$PATH"
source ~/.zshrc
```

**Port 4566 in use**
```bash
lsof -i :4566
kill -9 <PID>
```

## Version Requirements

**Minimum:** Docker 20.10+, Terraform 1.0+, AWS CLI 2.0+
**Recommended:** Docker 24.0+, Terraform 1.7+, AWS CLI 2.15+

## Next Steps

After installing, run `make check` then see [QUICKSTART.md](QUICKSTART.md)