# LocalStack AWS Development

> Fully functional local AWS cloud stack for development and testing.

- Category: Development Tools
- Difficulty: intermediate
- Components: localstack, aws-cli, dynamodb-admin
- Tags: localstack, aws, s3, lambda, dynamodb, development
- Source: https://docker.recipes/development/localstack-aws

## Overview

LocalStack is a fully functional local AWS cloud stack that emulates AWS services on your local machine, originally created by Atlassian engineers to solve the problem of expensive and slow AWS development cycles. It provides local implementations of services like S3, DynamoDB, Lambda, SQS, and API Gateway, allowing developers to test AWS applications without incurring cloud costs or dealing with network latency. LocalStack has become the de facto standard for AWS local development since its open-source release in 2017, supporting over 80 AWS services with high-fidelity emulation.

This stack combines LocalStack's core emulation engine with AWS CLI for command-line interactions and DynamoDB Admin for visual database management. LocalStack serves as the central hub on port 4566, handling all AWS service requests, while AWS CLI provides a pre-configured client for testing and automation scripts. DynamoDB Admin adds a web-based interface for inspecting and managing DynamoDB tables, creating a complete local AWS development environment that mirrors production workflows without requiring actual AWS resources.

This configuration is ideal for development teams building AWS-native applications, DevOps engineers creating infrastructure automation, and organizations wanting to reduce AWS development costs. The combination eliminates the need for separate AWS accounts for each developer, enables offline development, and provides faster feedback loops than cloud-based testing. Companies like Netflix, Airbnb, and thousands of startups use LocalStack to accelerate their AWS development cycles while maintaining production parity.

## Features

- Complete AWS service emulation including S3 buckets, DynamoDB tables, Lambda functions, SQS queues, SNS topics, and API Gateway endpoints
- Docker-reuse Lambda executor for faster function invocation and reduced container overhead during testing
- Pre-configured AWS CLI container with test credentials and LocalStack endpoint configuration
- Visual DynamoDB table browser and editor through DynamoDB Admin web interface
- Persistent data storage maintaining S3 objects, DynamoDB data, and Lambda deployments across container restarts
- CloudWatch logs and metrics collection for monitoring local AWS service usage
- Secrets Manager and Systems Manager Parameter Store for testing secure configuration management
- Multi-service integration testing with services communicating through LocalStack's internal routing

## Use cases

- Serverless application development with Lambda functions triggering from S3 events or API Gateway requests
- E-commerce platforms testing order processing workflows with DynamoDB, SQS, and SNS integration
- Infrastructure as Code validation using Terraform or CloudFormation against LocalStack endpoints
- CI/CD pipeline integration testing without provisioning actual AWS resources
- Microservices development with API Gateway routing, Lambda backends, and DynamoDB persistence
- Data processing pipeline development using S3 for storage, Lambda for processing, and SQS for queueing
- AWS certification study labs for hands-on practice with AWS services without cost concerns

## Prerequisites

- Docker Engine 20.10+ with at least 4GB RAM allocated for LocalStack service emulation
- 8GB system RAM minimum for running Lambda functions and multiple AWS services simultaneously
- Ports 4566, 4510-4559, and 8001 available for LocalStack services and DynamoDB Admin interface
- Basic AWS concepts knowledge including S3 buckets, DynamoDB tables, and Lambda functions
- Docker socket access (/var/run/docker.sock) for LocalStack's Lambda Docker executor
- Understanding of AWS CLI commands and endpoint URL configuration for local development

## docker-compose.yml

```yaml
services:
  localstack:
    image: localstack/localstack:latest
    ports:
      - "4566:4566"
      - "4510-4559:4510-4559"
    environment:
      - SERVICES=s3,sqs,sns,dynamodb,lambda,apigateway,cloudwatch,secretsmanager,ssm
      - DEBUG=1
      - DATA_DIR=/var/lib/localstack/data
      - LAMBDA_EXECUTOR=docker-reuse
      - DOCKER_HOST=unix:///var/run/docker.sock
    volumes:
      - localstack_data:/var/lib/localstack
      - /var/run/docker.sock:/var/run/docker.sock
    networks:
      - localstack-net
    restart: unless-stopped

  aws-cli:
    image: amazon/aws-cli:latest
    environment:
      - AWS_ACCESS_KEY_ID=test
      - AWS_SECRET_ACCESS_KEY=test
      - AWS_DEFAULT_REGION=us-east-1
    entrypoint: /bin/sh
    command: -c "sleep infinity"
    depends_on:
      - localstack
    networks:
      - localstack-net

  dynamodb-admin:
    image: aaronshaf/dynamodb-admin:latest
    ports:
      - "8001:8001"
    environment:
      - DYNAMO_ENDPOINT=http://localstack:4566
      - AWS_REGION=us-east-1
      - AWS_ACCESS_KEY_ID=test
      - AWS_SECRET_ACCESS_KEY=test
    depends_on:
      - localstack
    networks:
      - localstack-net
    restart: unless-stopped

volumes:
  localstack_data:

networks:
  localstack-net:
    driver: bridge
```

## .env

```bash
# LocalStack Configuration
SERVICES=s3,sqs,sns,dynamodb,lambda
DEBUG=1

# AWS CLI (for local development)
AWS_ACCESS_KEY_ID=test
AWS_SECRET_ACCESS_KEY=test
AWS_DEFAULT_REGION=us-east-1
```

## Usage notes

- LocalStack at http://localhost:4566
- DynamoDB Admin UI at http://localhost:8001
- Use --endpoint-url=http://localhost:4566 with AWS CLI
- Supports S3, SQS, SNS, DynamoDB, Lambda, and more

## Troubleshooting

- Lambda functions failing with 'Cannot connect to Docker': Ensure Docker socket is properly mounted and Docker daemon is running with correct permissions
- DynamoDB Admin showing connection errors: Verify LocalStack is fully started by checking http://localhost:4566/health before accessing admin interface
- AWS CLI commands hanging or timing out: Add --cli-read-timeout=0 and --cli-connect-timeout=60 flags for LocalStack compatibility
- S3 bucket operations returning 500 errors: Restart LocalStack container as S3 service may need reinitialization, especially after Lambda deployments
- Port 4566 connection refused: Check if LocalStack container started successfully and all required services initialized by examining container logs
- Lambda functions not persisting between restarts: Ensure localstack_data volume is properly mounted and DATA_DIR environment variable is set correctly

