How to Set Up LocalStack with Docker Compose: A Practical Guide for Local AWS Development

X (Twitter) Facebook Pinterest LinkedIn

LocalStack provides a fully functional local AWS cloud stack, allowing you to develop and test your cloud and serverless apps offline without incurring the costs of using real AWS services. It supports a wide range of AWS services, making it an invaluable tool for developers looking to ensure their applications work seamlessly on AWS. Deploying LocalStack using Docker Compose simplifies the setup process, enabling you to spin up your local AWS environment with minimal configuration. This guide will walk you through the steps to deploy LocalStack using Docker Compose.

Table of Contents

Prerequisites

Before starting, ensure you have the following:

Docker installed on your system.
Docker Compose installed on your system.
Basic understanding of Docker concepts and the YAML syntax used in Docker Compose files.

Step 1: Create a Docker Compose File

First, create a directory dedicated to your LocalStack setup. This directory will house your Docker Compose file (docker-compose.yml) and any additional configuration files or scripts you may need.

mkdir localstack-docker && cd localstack-docker

Next, create the docker-compose.yml file:

touch docker-compose.yml

Open this file in a text editor and add the following configuration:

version: '3.8'

services:
  localstack:
    image: localstack/localstack
    container_name: localstack_main
    ports:
      - "4566:4566" # Default LocalStack Edge port
      - "4571:4571" # Legacy port, useful for specific services
    environment:
      - SERVICES=s3,lambda,iam,dynamodb,apigateway # Specify the AWS services you want to mock
      - DEFAULT_REGION=us-east-1
      - DEBUG=1 # Enable debugging output (optional)
      - DATA_DIR=/tmp/localstack/data # Enable data persistence
    volumes:
      - "./.localstack:/tmp/localstack" # Persist LocalStack data
      - "/var/run/docker.sock:/var/run/docker.sock" # Docker daemon socket

volumes:
  .localstack:

Configuration Explained:

image: Specifies the LocalStack Docker image. Using localstack/localstack, you get the latest version.
container_name: Sets a custom name for the container.
ports: Exposes LocalStack’s default edge port (4566) and an additional legacy port (4571). These ports allow you to interact with the mocked AWS services.
environment:
- SERVICES: Defines which AWS services you want to mock. This list can be customized based on your development needs.
- DEFAULT_REGION: Sets the default AWS region for your services.
- DEBUG: Enables detailed debug output, useful for troubleshooting.
- DATA_DIR: Specifies the directory within the container where LocalStack will persist its data.
volumes:
- The first volume persists LocalStack’s data on your host machine, ensuring data retention across container restarts.
- The second volume mounts the Docker daemon socket, allowing LocalStack to spawn local Lambda functions in separate Docker containers.

Step 2: Launch LocalStack

Navigate to the directory containing your docker-compose.yml file. Start LocalStack by running the following command:

docker compose up -d

This command pulls the necessary Docker image (if not already pulled) and starts the LocalStack container in detached mode.

Step 3: Verify LocalStack is Running

To ensure LocalStack is up and running, you can list the running Docker containers:

docker ps

Look for the localstack_main container in the output. Additionally, you can test the LocalStack APIs directly by using awscli or any AWS SDK, configured to use localhost as the endpoint.

Step 4: Interact with LocalStack Services

With LocalStack running, you can now interact with the AWS services you specified in the SERVICES environment variable. For example, to create an S3 bucket, you can use the AWS CLI:

aws --endpoint-url=http://localhost:4566 s3 mb s3://my-test-bucket

Replace http://localhost:4566 with the appropriate URL if you’re accessing LocalStack from a different host or have customized the port mappings.

Conclusion

Deploying LocalStack with Docker Compose offers a streamlined approach to setting up a local AWS environment, allowing you to develop and test cloud applications without connecting to actual AWS services. Following the steps outlined in this guide, you can have a LocalStack instance running on your machine, ready to simulate a wide range of AWS services. This setup not only facilitates offline development but also helps reduce development costs and speed up the testing cycle.

Author
Recent Posts

Follow me

Anastasios Antoniadis

Anastasios Antoniadis is the founder and editor-in-chief of BORDERPOLAR... He is a software engineer, blogger, and avid gamer covering tech, gaming, and coding guides for over 4 years. He is a 2014 graduate of the Department of Informatics and Telecommunications of the University of Athens, an M.Sc. holder in Computer Science, and a Ph.D. student in Program Analysis.