docker.recipes

LocalStack AWS Development

intermediate

Fully functional local AWS cloud stack for development and testing.

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.

Key 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

Common Use Cases

  • 1Serverless application development with Lambda functions triggering from S3 events or API Gateway requests
  • 2E-commerce platforms testing order processing workflows with DynamoDB, SQS, and SNS integration
  • 3Infrastructure as Code validation using Terraform or CloudFormation against LocalStack endpoints
  • 4CI/CD pipeline integration testing without provisioning actual AWS resources
  • 5Microservices development with API Gateway routing, Lambda backends, and DynamoDB persistence
  • 6Data processing pipeline development using S3 for storage, Lambda for processing, and SQS for queueing
  • 7AWS 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

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

docker-compose.yml

docker-compose.yml
1services: 
2  localstack: 
3    image: localstack/localstack:latest
4    ports: 
5      - "4566:4566"
6      - "4510-4559:4510-4559"
7    environment: 
8      - SERVICES=s3,sqs,sns,dynamodb,lambda,apigateway,cloudwatch,secretsmanager,ssm
9      - DEBUG=1
10      - DATA_DIR=/var/lib/localstack/data
11      - LAMBDA_EXECUTOR=docker-reuse
12      - DOCKER_HOST=unix:///var/run/docker.sock
13    volumes: 
14      - localstack_data:/var/lib/localstack
15      - /var/run/docker.sock:/var/run/docker.sock
16    networks: 
17      - localstack-net
18    restart: unless-stopped
19
20  aws-cli: 
21    image: amazon/aws-cli:latest
22    environment: 
23      - AWS_ACCESS_KEY_ID=test
24      - AWS_SECRET_ACCESS_KEY=test
25      - AWS_DEFAULT_REGION=us-east-1
26    entrypoint: /bin/sh
27    command: -c "sleep infinity"
28    depends_on: 
29      - localstack
30    networks: 
31      - localstack-net
32
33  dynamodb-admin: 
34    image: aaronshaf/dynamodb-admin:latest
35    ports: 
36      - "8001:8001"
37    environment: 
38      - DYNAMO_ENDPOINT=http://localstack:4566
39      - AWS_REGION=us-east-1
40      - AWS_ACCESS_KEY_ID=test
41      - AWS_SECRET_ACCESS_KEY=test
42    depends_on: 
43      - localstack
44    networks: 
45      - localstack-net
46    restart: unless-stopped
47
48volumes: 
49  localstack_data: 
50
51networks: 
52  localstack-net: 
53    driver: bridge

.env Template

.env
1# LocalStack Configuration
2SERVICES=s3,sqs,sns,dynamodb,lambda
3DEBUG=1
4
5# AWS CLI (for local development)
6AWS_ACCESS_KEY_ID=test
7AWS_SECRET_ACCESS_KEY=test
8AWS_DEFAULT_REGION=us-east-1

Usage Notes

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

Individual Services(3 services)

Copy individual services to mix and match with your existing compose files.

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

Quick Start

terminal
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  localstack:
5    image: localstack/localstack:latest
6    ports:
7      - "4566:4566"
8      - "4510-4559:4510-4559"
9    environment:
10      - SERVICES=s3,sqs,sns,dynamodb,lambda,apigateway,cloudwatch,secretsmanager,ssm
11      - DEBUG=1
12      - DATA_DIR=/var/lib/localstack/data
13      - LAMBDA_EXECUTOR=docker-reuse
14      - DOCKER_HOST=unix:///var/run/docker.sock
15    volumes:
16      - localstack_data:/var/lib/localstack
17      - /var/run/docker.sock:/var/run/docker.sock
18    networks:
19      - localstack-net
20    restart: unless-stopped
21
22  aws-cli:
23    image: amazon/aws-cli:latest
24    environment:
25      - AWS_ACCESS_KEY_ID=test
26      - AWS_SECRET_ACCESS_KEY=test
27      - AWS_DEFAULT_REGION=us-east-1
28    entrypoint: /bin/sh
29    command: -c "sleep infinity"
30    depends_on:
31      - localstack
32    networks:
33      - localstack-net
34
35  dynamodb-admin:
36    image: aaronshaf/dynamodb-admin:latest
37    ports:
38      - "8001:8001"
39    environment:
40      - DYNAMO_ENDPOINT=http://localstack:4566
41      - AWS_REGION=us-east-1
42      - AWS_ACCESS_KEY_ID=test
43      - AWS_SECRET_ACCESS_KEY=test
44    depends_on:
45      - localstack
46    networks:
47      - localstack-net
48    restart: unless-stopped
49
50volumes:
51  localstack_data:
52
53networks:
54  localstack-net:
55    driver: bridge
56EOF
57
58# 2. Create the .env file
59cat > .env << 'EOF'
60# LocalStack Configuration
61SERVICES=s3,sqs,sns,dynamodb,lambda
62DEBUG=1
63
64# AWS CLI (for local development)
65AWS_ACCESS_KEY_ID=test
66AWS_SECRET_ACCESS_KEY=test
67AWS_DEFAULT_REGION=us-east-1
68EOF
69
70# 3. Start the services
71docker compose up -d
72
73# 4. View logs
74docker 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-aws/run | bash

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

Community Notes

Loading...
Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

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

Components

localstackaws-clidynamodb-admin

Tags

#localstack#aws#s3#lambda#dynamodb#development

Category

Development Tools

Related Recipes

Ad Space