LocalStack on Docker

LocalStack is a fully functional local AWS cloud stack that allows you to develop and test AWS applications locally without deploying to AWS. It emulates AWS services like S3, EC2, Lambda, DynamoDB, and many others on your local machine using Docker.

Quick Start

# 1. Install AWS CLI wrapper for LocalStack
pip install awscli-local

# 2. Start LocalStack
docker-compose up -d

# 3. Verify it's running (should return empty list)
awslocal s3 ls

Table of Contents

• Prerequisites
• Installation
• Configuration
• Running LocalStack
• Example AWS CLI Commands
• Data Persistence
• Available Ports
• Project Structure
• Troubleshooting

---

Prerequisites

Before you can use this LocalStack setup, ensure you have the following installed:

Required

• Docker: Version 20.10 or later (Install Docker)
• Docker Compose: Version 1.29 or later (Install Docker Compose)
• Python: Version 3.7 or later (for awscli-local)

Recommended

• Basic knowledge of AWS services (S3, EC2, Lambda, etc.)
• Familiarity with Docker and command-line tools

---

Installation

Step 1: Verify Docker and Docker Compose

# Check Docker version
docker --version

# Check Docker Compose version
docker-compose --version

Step 2: Install awscli-local

awscli-local is a wrapper around the AWS CLI that automatically redirects commands to your local LocalStack instance.

pip install awscli-local

Verify the installation:

awslocal --version

Step 3: Verify Your Setup Files

Ensure you have the following files in your project directory:

• docker-compose.yml: Contains the LocalStack service configuration
• .env: Contains your LocalStack authentication token

If these are missing, see the Configuration section below.

---

Configuration

Environment Variables (.env file)

The .env file contains your LocalStack Pro authentication token. This token grants you access to LocalStack Pro features.

Example .env:

LOCALSTACK_AUTH_TOKEN=ls-fOMIKusU-SUmA-retI-Nogi-RIbe19454f5b

What is LOCALSTACK_AUTH_TOKEN?

• It's your authentication token for LocalStack Pro
• It enables access to advanced AWS service emulations and additional features
• Keep this token secure and do not commit it to version control

Getting Your Token:

1. Create a free account at app.localstack.cloud
2. Navigate to your account dashboard
3. Generate or copy your authentication token
4. Paste it into your .env file as shown above

Security Note: Add .env to your .gitignore file to prevent committing sensitive tokens to version control.

Docker Compose Configuration (docker-compose.yml)

The docker-compose.yml file defines the LocalStack service and its configuration:

Key Components:

Component	Purpose
Image	localstack/localstack-pro - The LocalStack Pro Docker image (use localstack/localstack for Community edition)
Ports	4566 - Main LocalStack endpoint; 4510-4559 - Additional service endpoints
Environment Variables	Configure LocalStack behavior (debug, auth, DNS settings)
Volumes	Mount Docker socket for nested container support; persist data to ./localstack-data

Environment Variables:

• DEBUG=1: Enable debug logging for troubleshooting
• DOCKER_HOST: Allows LocalStack to start containers (nested Docker)
• LOCALSTACK_AUTH_TOKEN: Your authentication token (loaded from .env)
• DNS_ADDRESS=0: Use default DNS settings

---

Running LocalStack

Start LocalStack

# Start in the background
docker-compose up -d

# Or start in foreground to see logs
docker-compose up

Verify LocalStack is Running

# Check if the container is running
docker ps | grep localstack

# Test connectivity to LocalStack
awslocal s3 ls

If successful, the command will return an empty list (you haven't created any buckets yet).

Access LocalStack

• Main endpoint: http://localhost:4566
• Additional services: http://localhost:4510-4559

Stop LocalStack

docker-compose down

View Logs

# View current logs
docker-compose logs -f localstack

# View last 100 lines
docker-compose logs --tail=100 localstack

---

Example AWS CLI Commands

Once LocalStack is running, you can use awslocal to interact with AWS services locally.

S3 Bucket Operations

# Create a bucket
awslocal s3 mb s3://my-test-bucket

# List all buckets
awslocal s3 ls

# Upload a file
awslocal s3 cp myfile.txt s3://my-test-bucket/

# List bucket contents
awslocal s3 ls s3://my-test-bucket/

# Download a file
awslocal s3 cp s3://my-test-bucket/myfile.txt ./downloaded-file.txt

DynamoDB Operations

# Create a table
awslocal dynamodb create-table \
  --table-name Users \
  --attribute-definitions AttributeName=id,AttributeType=S \
  --key-schema AttributeName=id,KeyType=HASH \
  --billing-mode PAY_PER_REQUEST

# List tables
awslocal dynamodb list-tables

# Put an item
awslocal dynamodb put-item \
  --table-name Users \
  --item '{"id": {"S": "user123"}, "name": {"S": "John Doe"}}'

Lambda Operations

# List functions
awslocal lambda list-functions

# Create a function (requires a zip file)
awslocal lambda create-function \
  --function-name my-function \
  --runtime python3.9 \
  --role arn:aws:iam::000000000000:role/lambda-role \
  --handler index.handler \
  --zip-file fileb://function.zip

---

Data Persistence

LocalStack stores data in the ./localstack-data directory, which is mounted as a volume in the Docker container.

Directory Structure

localstack-data/
├── cache/          # LocalStack cache files
│   ├── certs/      # SSL certificates for HTTPS
│   ├── license.json # License information
│   └── machine.json # Machine configuration
├── lib/            # Library files
├── logs/           # LocalStack logs (if configured)
└── tmp/            # Temporary files

Persistence Behavior

• Enabled by default: Data persists between container restarts
• Data preserved in volumes: Buckets, tables, functions, etc., remain even after docker-compose down
• Clean slate: To reset all data, delete the localstack-data directory or run a reset command (see Troubleshooting)

---

Available Ports

Port	Purpose
4566	Main LocalStack endpoint (S3, DynamoDB, Lambda, etc.)
4510-4559	Additional service-specific endpoints (reserved for future use)

All services can be accessed via the main endpoint (4566). The additional ports are available if needed for specific configurations.

---

Project Structure

localstack/
├── docker-compose.yml          # Docker Compose configuration file
├── .env                        # Environment variables (authentication token)
├── README.md                   # This file
├── localstack-data/            # Data persistence volume
│   ├── cache/                  # Cache and certificates
│   ├── lib/                    # Library files
│   ├── logs/                   # Log files
│   └── tmp/                    # Temporary files

File Descriptions

• docker-compose.yml: Defines the LocalStack service configuration, ports, volumes, and environment variables
• .env: Contains sensitive configuration (authentication token) - do not commit to Git
• README.md: Project documentation (this file)
• localstack-data/: Volume mount directory for persistent data storage

---

Troubleshooting

Issue: Port 4566 Already in Use

Problem: docker-compose up fails with "port is already allocated"

Solution:

1. Identify what's using port 4566:

   netstat -ano | findstr :4566

2. Either stop the conflicting service or change the port in docker-compose.yml:

   ports:
     - "4567:4566"  # Map 4567 on host to 4566 in container

Issue: Authentication Token Invalid

Problem: Commands fail with authentication errors

Solution:

1. Verify your token is correct in .env
2. Ensure .env is in the same directory as docker-compose.yml
3. Regenerate your token at app.localstack.cloud
4. Update .env with the new token
5. Restart LocalStack: docker-compose down && docker-compose up -d

Issue: Cannot Connect to LocalStack

Problem: awslocal commands fail to connect

Solution:

1. Verify LocalStack is running:

   docker ps | grep localstack

2. Check logs for errors:

   docker-compose logs localstack

3. Ensure Docker daemon is running
4. On macOS/Windows, ensure Docker Desktop is started

Issue: "Cannot connect to Docker daemon"

Problem: Docker commands fail

Solution:

• Docker Desktop: Start the Docker Desktop application
• Linux: Ensure Docker daemon is running: sudo systemctl start docker
• Permission denied: Add your user to Docker group: sudo usermod -aG docker $USER

Issue: Services Not Available

Problem: Trying to use a service that doesn't exist or isn't emulated

Solution:

• Check LocalStack Pro Supported Services
• Verify you're using LocalStack Pro (for extended service support)
• Update LocalStack image: docker pull localstack/localstack-pro

Debug Mode

To enable debug logging for troubleshooting, the setup already has DEBUG=1 enabled. View detailed logs:

docker-compose logs -f localstack | grep -i error

Reset LocalStack (Clear All Data)

To start fresh with no data:

# Stop the container
docker-compose down -v

# Remove the data directory
rm -rf localstack-data

# Start fresh
docker-compose up -d

Warning: This will delete all data (buckets, tables, functions, etc.)

Using LocalStack Community Edition

To use the free Community edition instead of Pro:

1. Edit docker-compose.yml:

   image: localstack/localstack  # Change from localstack-pro

2. Remove the LOCALSTACK_AUTH_TOKEN environment variable (or leave it blank)

3. Restart: docker-compose down && docker-compose up -d

---

Additional Resources

• LocalStack Official Documentation
• AWS CLI Documentation
• Docker Documentation
• awscli-local GitHub

---

Next Steps

1. ✅ Verify prerequisites are installed
2. ✅ Install awscli-local
3. ✅ Start LocalStack with docker-compose up -d
4. ✅ Test connectivity with awslocal s3 ls
5. ✅ Try example commands from Example AWS CLI Commands
6. ✅ Explore LocalStack documentation for advanced features