With over 52,000 stars and 520+ contributors, LocalStack is an open-source tool that emulates a wide range of AWS services on a local machine. It’s primarily used for testing and development purposes, allowing developers to run applications locally without needing to interact with the actual AWS cloud.
LocalStack is a cloud development platform that solves the challenge of costly and slow cloud resource usage during development and testing of serverless applications. By providing a local environment that replicates AWS services, LocalStack helps developers ensure that their applications work correctly before deploying them to a live environment.
Key features of LocalStack include:
- Service Emulation: It emulates various AWS services such as S3, DynamoDB, Lambda, API Gateway, SQS, SNS, CloudFormation, and more.
- Local Development: Developers can run AWS services locally, which speeds up development cycles and reduces costs associated with using AWS resources.
- Consistency: Ensures that the development environment closely mirrors the production environment on AWS, reducing discrepancies and potential issues during deployment.
- Automation and CI/CD Integration: LocalStack can be integrated into CI/CD pipelines, enabling automated testing of AWS-dependent code.
- LocalStack can be run using Docker, making it easy to set up and use on various platforms.
Benefits of using Localstack:
- Reduced Costs: By emulating AWS services locally, LocalStack eliminates the need to constantly deploy to the cloud, saving you money on cloud charges.
- Faster Development: LocalStack lets you spin up services instantly on your machine, significantly speeding up development cycles compared to waiting for cloud deployments.
Getting Started
Installing LocalStack on your MacOS:
Copied!brew install localstack/tap/localstack-cli
You can directly start the LocalStack container using the Docker CLI. This method requires more manual steps and configuration, but it gives you more control over the container settings.
The first time you start localstack, it requires Docker daemon to be up and running on your system.
Copied!localstack start -d __ _______ __ __ / / ____ _________ _/ / ___// /_____ ______/ /__ / / / __ \/ ___/ __ `/ /\__ \/ __/ __ `/ ___/ //_/ / /___/ /_/ / /__/ /_/ / /___/ / /_/ /_/ / /__/ ,< /_____/\____/\___/\__,_/_//____/\__/\__,_/\___/_/|_| 💻 LocalStack CLI 3.5.0 👤 Profile: default [09:22:54] starting LocalStack in Docker mode 🐳 localstack.py:503 preparing environment bootstrap.py:1283 ERROR: '['docker', 'ps']': exit code 1; output: b'Cannot connect to the Docker daemon at unix:///Users/ajeetsraina/.docker/run/docker.sock. Is the docker daemon running?\n' ❌ Error: Docker could not be found on the system. Please make sure that you have a working docker environment on your machine.
Install Docker Desktop on your system and now this time you will find that Localstack gets started successfully.
Copied!localstack start -d __ _______ __ __ / / ____ _________ _/ / ___// /_____ ______/ /__ / / / __ \/ ___/ __ `/ /\__ \/ __/ __ `/ ___/ //_/ / /___/ /_/ / /__/ /_/ / /___/ / /_/ /_/ / /__/ ,< /_____/\____/\___/\__,_/_//____/\__/\__,_/\___/_/|_| 💻 LocalStack CLI 3.5.0 👤 Profile: default [09:23:54] starting LocalStack in Docker mode 🐳 localstack.py:503 preparing environment bootstrap.py:1283 configuring container bootstrap.py:1291 starting container bootstrap.py:1301 [09:23:55] detaching bootstrap.py:1305
You can also start the Docker container simply by executing the following docker run command:
Copied!$ docker run --rm -it -p 4566:4566 -p 4510-4559:4510-4559 localstack/localstack
List of AWS services that Localstack support
Copied!localstack status services ┏━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┓ ┃ Service ┃ Status ┃ ┡━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━┩ │ acm │ ✔ available │ │ apigateway │ ✔ available │ │ cloudformation │ ✔ available │ │ cloudwatch │ ✔ available │ │ config │ ✔ available │ │ dynamodb │ ✔ available │ │ dynamodbstreams │ ✔ available │ │ ec2 │ ✔ available │ │ es │ ✔ available │ │ events │ ✔ available │ │ firehose │ ✔ available │ │ iam │ ✔ available │ │ kinesis │ ✔ available │ │ kms │ ✔ available │ │ lambda │ ✔ available │ │ logs │ ✔ available │ │ opensearch │ ✔ available │ │ redshift │ ✔ available │ │ resource-groups │ ✔ available │ │ resourcegroupstaggingapi │ ✔ available │ │ route53 │ ✔ available │ │ route53resolver │ ✔ available │ │ s3 │ ✔ available │ │ s3control │ ✔ available │ │ scheduler │ ✔ available │ │ secretsmanager │ ✔ available │ │ ses │ ✔ available │ │ sns │ ✔ available │ │ sqs │ ✔ available │ │ ssm │ ✔ available │ │ stepfunctions │ ✔ available │ │ sts │ ✔ available │ │ support │ ✔ available │ │ swf │ ✔ available │ │ transcribe │ ✔ available │ └──────────────────────────┴─────────────┘
Creating a AWS S3 Bucket
Create an s3 bucket with LocalStack’s awslocal CLI:
Copied!awslocal s3api create-bucket --bucket sample-bucket { "Location": "/sample-bucket" }
Listing the S3 Bucket
Copied!awslocal s3api list-buckets { "Buckets": [ { "Name": "sample-bucket", "CreationDate": "2024-06-29T17:56:46.000Z" } ], "Owner": { "DisplayName": "webfile", "ID": "75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a" } }
Listingthe items inside the bucket:
Copied!awslocal s3api list-objects --bucket sample-bucket { "RequestCharged": null }
Running Localstack using Docker Compose
Copied!services: localstack: container_name: "${LOCALSTACK_DOCKER_NAME:-localstack-main}" 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: # LocalStack configuration: https://docs.localstack.cloud/references/configuration/ - DEBUG=${DEBUG:-0} volumes: - "${LOCALSTACK_VOLUME_DIR:-./volume}:/var/lib/localstack" - "/var/run/docker.sock:/var/run/docker.sock"
Starting the container
Copied!docker compose up [+] Running 1/0 ✔ Container localstack_demo Recreated 0.1s Attaching to localstack-main localstack-main | localstack-main | LocalStack version: 3.5.1.dev localstack-main | LocalStack build date: 2024-06-24 localstack-main | LocalStack build git hash: 9a3d238ac localstack-main | localstack-main | Ready.
Creating a queue using SQS with LocalStack’s awslocal CLI:
Copied!$ awslocal sqs create-queue --queue-name test-queue
Result:
Copied!{ "QueueUrl": "http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/test-queue" }
Copied!$ awslocal sqs list-queues
Result:
Copied!{ "QueueUrls": [ "http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/test-queue" ] }
Auto-Create S3 Bucket
To automatically create an S3 bucket when running LocalStack with Docker Compose, follow this approach:
Update Your Docker Compose File
Add a volume mount for an initialization script to the container.
Use the /etc/localstack/init/ready.d directory for hooks in LocalStack.
Example updated docker-compose.yml:
Copied!services: localstack: container_name: "${LOCALSTACK_DOCKER_NAME:-localstack-main}" 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: - DEBUG=${DEBUG:-0} - SERVICES=s3 # Ensure S3 service is enabled volumes: - "${LOCALSTACK_VOLUME_DIR:-./volume}:/var/lib/localstack" - "/var/run/docker.sock:/var/run/docker.sock" - "./scripts:/etc/localstack/init/ready.d" # Mount the script directory
Create an Initialization Script
- Place the script in the
./scriptsdirectory (as defined in thedocker-compose.ymlfile). - The script will execute when the container starts and create the desired S3 bucket(s).
Example scripts/init-s3.sh:
Copied!#!/usr/bin/env bash set -e export AWS_ACCESS_KEY_ID=test export AWS_SECRET_ACCESS_KEY=test export AWS_DEFAULT_REGION=us-east-1 echo "Creating S3 bucket..." awslocal s3 mb s3://sample-bucket echo "S3 bucket 'sample-bucket' created."
Ensure Permissions
Make the script executable by running:
Copied!chmod +x ./scripts/init-s3.sh
Run Docker Compose
Start LocalStack with Docker Compose:
Copied!docker compose up
Verify Bucket Creation
List the buckets using awslocal to confirm:
Copied!awslocal s3api list-buckets
Output:
Copied!{ "Buckets": [ { "Name": "sample-bucket", "CreationDate": "2024-06-29T17:56:46.000Z" } ], "Owner": { "DisplayName": "webfile", "ID": "75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a" } }
Why This Works
- LocalStack executes scripts located in the
/etc/localstack/init/ready.ddirectory as part of the initialization process. - This ensures that your S3 bucket is created every time the container starts, automating the setup process.
Other Optional Enhancements
Create Multiple Buckets
Modify the init-s3.sh script to create additional buckets:
Copied!awslocal s3 mb s3://bucket1 awslocal s3 mb s3://bucket2
Preload Objects
Add objects to the bucket using the AWS CLI in the script:
Copied!awslocal s3 cp /path/to/file s3://bucket1/key
Verify Bucket Creation in CI/CD
Add a health check using the AWS CLI to confirm that the bucket is created:
Copied!awslocal s3api head-bucket --bucket bucket1
By following these steps, you can integrate automatic S3 bucket creation seamlessly into your LocalStack setup.
References:
Leave a Reply