Entrypoint Script with Localstack and Docker-Compose

Technical Stack: AWS, Localstack, Docker, Docker-Compose

Read: 5 minutes

Prerequisites

• Docker, Docker-Compose
• Localstack Docker Image

This guide has been updated for Localstack releases after March 29, 2023. Read More Here.

Earlier versions of Localstack Lambda reference /docker-entrypoint-initaws.d/ for entrypoint scripts. That entrypoint path was deprecated in v1.1.0.

Introduction

Localstack is a cloud service emulator that runs in a single container on your laptop or in your CI environment. Read More Here.

awslocal is a thin wrapper for AWS CLI that overrides the AWS CLI commands with --endpoint-url localhost:4566.

After reading this, your docker-compose will:

• Run Localstack in Docker-Compose
• Create mocked resources in Localstack with entrypoint scripts
• How to access Localstack services at http://localstack:4566 or using awslocal

Entrypoint Script to Create S3 Buckets in Localstack

• Create and paste the following content to start-localstack.sh. This will be our entrypoint scipt:

#!/bin/bash
awslocal s3 mb s3://hsl-local-terraform --region us-west-2
awslocal s3 mb s3://hsl-local-serverless --region us-west-2
awslocal s3 ls --region us-west-2

• Make the script executable by running:

chmod +x start-localstack.sh

• Pass the start-localstack.sh through the volumes: section to the localstack container:

  1. Pass entrypoint startup scripts through /etc/localstack/init/ready.d/
  2. Read here for a full list of Localstack Lifecycle Events
  3. Use the docker-compose.yml below as a reference.

• Start the containers using docker-compose up and observe the S3 buckets being made:

relate-lambda-template-localstack-1  | make_bucket: hsl-local-serverless
relate-lambda-template-localstack-1  | {
relate-lambda-template-localstack-1  |     "EventBusArn": "arn:aws:events:us-west-2:000000000000:event-bus/platform-service-bus"
relate-lambda-template-localstack-1  | }
relate-lambda-template-localstack-1  | 2023-06-22 04:45:49 hsl-local-serverless

Full Docker-Compose Example

version: "3.8" 
services:
  localstack:
    image: localstack/localstack
    ports:
      - "127.0.0.1:4566:4566"            # LocalStack Gateway
      - "127.0.0.1:4510-4559:4510-4559"  # external services port range
    environment:
      AWS_DEFAULT_REGION: us-west-2
      AWS_ACCESS_KEY_ID: test
      AWS_SECRET_ACCESS_KEY: test
      DEBUG: ${DEBUG:-1}
      DOCKER_HOST: unix:///var/run/docker.sock
      LS_LOG: WARN  # Localstack DEBUG Level    
    volumes:
      - "${TMPDIR:-/tmp}/localstack:/var/lib/localstack"
      - "/var/run/docker.sock:/var/run/docker.sock"
      - ./start-localstack.sh:/etc/localstack/init/ready.d/start-localstack.sh

docker-compose.yml

Access Localstack S3 Buckets

Access From Local Machine

1. Run this awslocal from your local machine:

$ awslocal s3 ls

2023-06-21 21:45:49 hsl-local-serverless

Access from Localstack Container

• Access the localstack container by running:

$ docker-compose exec localstack /bin/bash

• Use awslocal to access the S3 buckets:

$ awslocal s3 ls

2023-06-22 04:45:49 hsl-local-serverless

Access From Compose Services

1. Override Boto3 Client Endpoint URL. This will point to the Localstack container:

import boto3

sns_client = boto3.client('sns', endpoint_url='http://localstack:4566')

Benefits of Localstack

• Developers can spin up a fully localized enviornment
• Less $$ spent provisioning and cleaning up AWS
• Isolated developer environments

I hope this guide helps you quickly orchestrate localstack next to your existing applications!