Entrypoint Script with Localstack and Docker-Compose

Posted by Miguel Lopez on Mon 16 January 2023 in localstack

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

Read: 5 minutes


  • 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.


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:
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" 
    image: localstack/localstack
      - ""            # LocalStack Gateway
      - ""  # external services port range
      AWS_DEFAULT_REGION: us-west-2
      AWS_ACCESS_KEY_ID: test
      DEBUG: ${DEBUG:-1}
      DOCKER_HOST: unix:///var/run/docker.sock
      LS_LOG: WARN  # Localstack DEBUG Level    
      - "${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


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!