LocalStack

intermediate

Local AWS cloud stack for development.

Overview

LocalStack is a fully functional local AWS cloud stack that emulates Amazon Web Services infrastructure on your local machine. Originally created by Atlassian and now maintained by LocalStack Inc., it provides a comprehensive testing environment that mimics AWS services without requiring actual cloud resources or incurring costs. This implementation runs the core LocalStack service configured with essential AWS services including S3 for object storage, SQS for message queuing, SNS for notifications, DynamoDB for NoSQL database operations, and Lambda for serverless function execution. This LocalStack deployment creates a local development environment that intercepts AWS API calls and processes them locally through a single gateway endpoint on port 4566. The configuration includes Docker socket mounting to enable full Lambda function execution capabilities, debug logging for development visibility, and persistent data storage to maintain state between container restarts. The service emulation handles authentication, request parsing, and response formatting to match AWS behavior patterns exactly. This stack is ideal for developers building AWS-native applications, DevOps teams implementing infrastructure as code, and organizations wanting to reduce cloud development costs while maintaining AWS compatibility. The combination of multiple AWS services in a single container makes it particularly valuable for testing complex workflows involving cross-service interactions, such as S3 event triggers invoking Lambda functions or DynamoDB streams feeding into SQS queues.

Key Features

Multi-service AWS emulation with S3, SQS, SNS, DynamoDB, and Lambda running in unified gateway
Docker-in-Docker Lambda execution environment supporting Python, Node.js, Java, and Go runtimes
Cross-service event triggering including S3 bucket notifications and DynamoDB streams
AWS CLI and SDK compatibility with endpoint URL override for transparent integration
IAM policy simulation and role-based access control testing without AWS account requirements
CloudFormation template deployment and stack management for infrastructure as code testing
Real-time debug logging with detailed AWS API request and response inspection
Persistent volume storage maintaining service state and data across container lifecycle

Common Use Cases

1Local development of serverless applications using Lambda functions with S3 triggers and DynamoDB storage
2Testing AWS CDK or CloudFormation templates before deploying to production environments
3Building and debugging microservices that integrate multiple AWS services without cloud costs
4CI/CD pipeline integration for automated testing of AWS-dependent applications
5Training and educational environments for learning AWS services without account billing
6Offline development scenarios where internet connectivity to AWS is limited or restricted
7Load testing applications against AWS services without impacting production quotas or costs

Prerequisites

Docker Engine 20.10+ with Docker Compose v2 for container orchestration support
Minimum 4GB RAM allocated to Docker for multiple AWS service emulation
Available ports 4566 and 4510-4559 for LocalStack gateway and service-specific endpoints
AWS CLI v2 installed locally for testing service interactions and data management
Basic understanding of AWS service concepts and API patterns for effective testing
Docker socket access permissions for Lambda function execution capabilities

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  localstack: 
3    image: localstack/localstack:latest
4    container_name: localstack
5    restart: unless-stopped
6    environment: 
7      SERVICES: s3,sqs,sns,dynamodb,lambda
8      DEBUG: 1
9    volumes: 
10      - localstack_data:/var/lib/localstack
11      - /var/run/docker.sock:/var/run/docker.sock
12    ports: 
13      - "4566:4566"
14      - "4510-4559:4510-4559"
15
16volumes: 
17  localstack_data:

.env Template

.env

1# Configure AWS CLI: aws --endpoint-url=http://localhost:4566

Usage Notes

1Docs: https://docs.localstack.cloud/
2Gateway at http://localhost:4566 - all AWS services here
3AWS CLI: aws --endpoint-url=http://localhost:4566 s3 ls
4Configure SERVICES env var to enable specific services
5Docker socket mount enables Lambda function execution
6Free tier covers S3, SQS, SNS, DynamoDB, Lambda basics

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  localstack:
5    image: localstack/localstack:latest
6    container_name: localstack
7    restart: unless-stopped
8    environment:
9      SERVICES: s3,sqs,sns,dynamodb,lambda
10      DEBUG: 1
11    volumes:
12      - localstack_data:/var/lib/localstack
13      - /var/run/docker.sock:/var/run/docker.sock
14    ports:
15      - "4566:4566"
16      - "4510-4559:4510-4559"
17
18volumes:
19  localstack_data:
20EOF
21
22# 2. Create the .env file
23cat > .env << 'EOF'
24# Configure AWS CLI: aws --endpoint-url=http://localhost:4566
25EOF
26
27# 3. Start the services
28docker compose up -d
29
30# 4. View logs
31docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/localstack/run | bash

Troubleshooting

Lambda functions failing to execute: Ensure Docker socket is properly mounted and Docker daemon is accessible from within container
Services not responding on port 4566: Check SERVICES environment variable includes required service names and container has fully started
AWS CLI commands returning connection errors: Verify endpoint URL parameter is set to http://localhost:4566 and LocalStack container is running
DynamoDB tables not persisting: Confirm localstack_data volume is properly mounted and has write permissions
S3 bucket operations timing out: Increase Docker memory allocation as S3 emulation requires additional resources for large file operations
CloudFormation stack deployment failures: Enable debug logging and check LocalStack logs for unsupported resource types or API limitations

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

localstack

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download