Skip to main content

LocalStack Installation

What is LocalStack?​

LocalStack is a cloud emulator that simulates AWS services on your local machine. It allows you to develop and test AWS applications without:

  • Creating an AWS account
  • Paying anything
  • Risking accidental billing
┌─────────────────────────────────────────────────────────────┐
│                      LocalStack                              │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│   Your Machine                    "Fake" AWS                 │
│   ┌─────────────┐                ┌─────────────────┐        │
│   │   AWS CLI   │ ──────────►    │   LocalStack    │        │
│   │   Scripts   │   Port 4566    │   (Docker)      │        │
│   │   Apps      │                │                 │        │
│   └─────────────┘                │   Services:     │        │
│                                  │   • S3          │        │
│                                  │   • Lambda      │        │
│                                  │   • DynamoDB    │        │
│                                  │   • SQS/SNS     │        │
│                                  │   • CloudWatch  │        │
│                                  │   • etc.        │        │
│                                  └─────────────────┘        │
│                                                              │
│   ✅ Free       ✅ Local     ✅ No AWS account needed        │
└─────────────────────────────────────────────────────────────┘

Prerequisites​

Docker Desktop (Mandatory)​

LocalStack runs in a Docker container. You must first install Docker Desktop.

Download:

Verify Docker​

# Verify Docker is installed
docker --version

# Verify Docker is working
docker run hello-world

Expected result:

Docker version 24.x.x, build xxxxx
Important Windows

On Windows, Docker Desktop must be started before using LocalStack. Check the Docker icon in the taskbar.

LocalStack Installation​

This is the simplest and most reliable method.

Start LocalStack:

docker run -d \
  --name localstack \
  -p 4566:4566 \
  -p 4510-4559:4510-4559 \
  -e SERVICES=s3,lambda,sqs,dynamodb,cloudwatch,cloudformation \
  -e DEBUG=1 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  localstack/localstack

On Windows PowerShell:

docker run -d `
  --name localstack `
  -p 4566:4566 `
  -p 4510-4559:4510-4559 `
  -e SERVICES=s3,lambda,sqs,dynamodb,cloudwatch,cloudformation `
  -e DEBUG=1 `
  localstack/localstack

Create a docker-compose.yml file:

version: '3.8'

services:
  localstack:
    container_name: localstack
    image: localstack/localstack:latest
    ports:
      - "4566:4566"            # Main port
      - "4510-4559:4510-4559"  # Additional ports
    environment:
      - SERVICES=s3,lambda,sqs,sns,dynamodb,cloudwatch,cloudformation,iam
      - DEBUG=1
      - DATA_DIR=/tmp/localstack/data
      - DOCKER_HOST=unix:///var/run/docker.sock
    volumes:
      - "${LOCALSTACK_VOLUME_DIR:-./volume}:/var/lib/localstack"
      - "/var/run/docker.sock:/var/run/docker.sock"

Start with Docker Compose:

docker-compose up -d

Method 3: Via pip (Alternative)​

# Install LocalStack CLI
pip install localstack

# Start LocalStack
localstack start

Installation Verification​

Step 1: Verify the container is running​

docker ps

Expected result:

CONTAINER ID   IMAGE                   COMMAND                  STATUS          PORTS
abc123def456   localstack/localstack   "docker-entrypoint.sh"   Up 2 minutes    0.0.0.0:4566->4566/tcp

Step 2: Check LocalStack status​

curl http://localhost:4566/_localstack/health

Expected result:

{
  "services": {
    "s3": "running",
    "lambda": "running",
    "sqs": "running",
    "dynamodb": "running",
    ...
  }
}

On Windows PowerShell:

Invoke-RestMethod http://localhost:4566/_localstack/health

Step 3: Test with AWS CLI​

# Create an S3 bucket
aws --endpoint-url=http://localhost:4566 s3 mb s3://my-first-bucket --profile localstack

# List buckets
aws --endpoint-url=http://localhost:4566 s3 ls --profile localstack

Expected result:

make_bucket: my-first-bucket
2024-12-18 10:30:00 my-first-bucket

Available LocalStack Services​

Free Version (Community)​

ServiceSupportNotes
S3✅ CompleteObject storage
Lambda✅ CompleteServerless functions
SQS✅ CompleteMessage queue
SNS✅ CompleteNotifications
DynamoDB✅ CompleteNoSQL database
CloudWatch Logs✅ PartialLogs only
CloudFormation✅ BasicSimple templates
IAM✅ BasicRoles and policies
EC2⚠️ LimitedMetadata only
VPC⚠️ LimitedBasic simulation

What we will use​

┌─────────────────────────────────────────────────────────────┐
│              LocalStack Services for this course             │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│   FULL PRACTICE               THEORY ONLY                    │
│   (LocalStack)                (No simulation)                │
│                                                              │
│   ✅ S3                        📚 EC2 (instances)            │
│   ✅ Lambda                    📚 Full VPC                   │
│   ✅ SQS/SNS                   📚 EBS                        │
│   ✅ DynamoDB                  📚 ELB/ALB                    │
│   ✅ CloudWatch Logs           📚 Route 53                   │
│   ✅ CloudFormation            📚 Auto Scaling               │
│   ✅ IAM (basic)                                            │
│                                                              │
└─────────────────────────────────────────────────────────────┘

LocalStack Management Commands​

Start LocalStack​

# With Docker
docker start localstack

# With Docker Compose
docker-compose up -d

# With CLI
localstack start

Stop LocalStack​

# With Docker
docker stop localstack

# With Docker Compose
docker-compose down

# With CLI
localstack stop

View logs​

docker logs localstack

# Follow logs in real-time
docker logs -f localstack

Clean restart​

docker stop localstack
docker rm localstack
# Then rerun the docker run command

Automation Script​

Create a script to ease the startup:

Windows (start-localstack.ps1)​

# start-localstack.ps1
Write-Host "Starting LocalStack..." -ForegroundColor Green

# Check if the container exists
$container = docker ps -a -q -f name=localstack

if ($container) {
    Write-Host "Removing old container..."
    docker rm -f localstack
}

# Start LocalStack
docker run -d `
    --name localstack `
    -p 4566:4566 `
    -p 4510-4559:4510-4559 `
    -e SERVICES=s3,lambda,sqs,dynamodb,cloudwatch,cloudformation `
    localstack/localstack

Write-Host "Waiting for startup (30 seconds)..." -ForegroundColor Yellow
Start-Sleep -Seconds 30

# Verify
Write-Host "Verification..." -ForegroundColor Green
aws --endpoint-url=http://localhost:4566 s3 ls --profile localstack

Write-Host "LocalStack is ready!" -ForegroundColor Green

macOS/Linux (start-localstack.sh)​

#!/bin/bash
echo "Starting LocalStack..."

# Remove old container if it exists
docker rm -f localstack 2>/dev/null

# Start LocalStack
docker run -d \
    --name localstack \
    -p 4566:4566 \
    -p 4510-4559:4510-4559 \
    -e SERVICES=s3,lambda,sqs,dynamodb,cloudwatch,cloudformation \
    localstack/localstack

echo "Waiting for startup (30 seconds)..."
sleep 30

# Verify
echo "Verification..."
aws --endpoint-url=http://localhost:4566 s3 ls --profile localstack

echo "LocalStack is ready!"

Handy Aliases​

To simplify commands, set up an alias:

Windows PowerShell​

Add to the $PROFILE file:

function awslocal {
    aws --endpoint-url=http://localhost:4566 --profile localstack $args
}

macOS/Linux​

Add to ~/.bashrc or ~/.zshrc:

alias awslocal='aws --endpoint-url=http://localhost:4566 --profile localstack'

Using the alias​

# Instead of:
aws --endpoint-url=http://localhost:4566 s3 ls --profile localstack

# You will write:
awslocal s3 ls

Complete Environment Test​

Run these commands to validate your installation:

# 1. Verify Docker
docker --version

# 2. Verify LocalStack
docker ps | grep localstack

# 3. Check health
curl http://localhost:4566/_localstack/health

# 4. Create an S3 bucket
awslocal s3 mb s3://test-bucket

# 5. List buckets
awslocal s3 ls

# 6. Delete the test bucket
awslocal s3 rb s3://test-bucket

# 7. Check Lambda (should be empty)
awslocal lambda list-functions

Expected Screenshot​

PS C:\Users\YourName> docker ps
CONTAINER ID   IMAGE                   STATUS          PORTS
abc123         localstack/localstack   Up 5 minutes    0.0.0.0:4566->4566/tcp

PS C:\Users\YourName> awslocal s3 ls
2024-12-18 10:30:00 test-bucket

PS C:\Users\YourName> awslocal lambda list-functions
{
    "Functions": []
}

Troubleshooting​

Problem: "Cannot connect to the Docker daemon"​

Solution:

  1. Ensure Docker Desktop is started
  2. On Windows, click the Docker icon in the taskbar
  3. Wait for Docker to be "Running"

Problem: "Port 4566 already in use"​

Solution:

# Find the process
# Windows
netstat -ano | findstr 4566

# Linux/macOS
lsof -i :4566

# Kill the process or change the port
docker run -p 4567:4566 ...

Problem: "Connection refused to localhost:4566"​

Solution:

  1. Wait 30-60 seconds after startup
  2. Check logs: docker logs localstack
  3. Restart the container

Problem: AWS commands very slow​

Solution: LocalStack can be slow on the first call. This is normal. Subsequent calls will be faster.

Validation Checklist​

  • Docker Desktop installed and started
  • LocalStack container running
  • Port 4566 accessible
  • Command awslocal s3 ls works
  • Alias awslocal configured

Validation Quiz​

  1. What is LocalStack?
  2. On which port does LocalStack listen by default?
  3. Why do we use --endpoint-url with AWS CLI?
  4. Which AWS services does LocalStack emulate well?
  5. How to verify that LocalStack is working?

Next section: Lab: Environment Setup