Setting Up an S3 Bucket in LocalStack

Introduction

Working with Amazon S3 is common for cloud storage solutions, but for local testing, interacting with AWS can be inefficient and costly. LocalStack is a fully functional local AWS cloud stack that emulates AWS services. In this guide, we’ll walk through how to set up an S3 bucket in LocalStack on macOS, discuss the benefits of using this setup, and provide a full code example.

Why Use LocalStack for S3?

Using LocalStack to simulate S3 provides key benefits:

Cost Efficiency: You avoid charges from AWS.
Speed: Tests are faster since they run locally.
Offline Testing: No internet connection required.
Isolation: Reduces risks of accidentally affecting real AWS resources.

Prerequisites

Ensure the following are installed on your respective OS:

Docker (required for LocalStack) - Download here.
Python & pip (needed for AWS CLI and boto3).
LocalStack via pip or Docker.

Step 1: Install and Start LocalStack

Install LocalStack:

brew install localstack

Run LocalStack as a Docker container:

localstack start

Note: If you face permissions issues, prepend sudo to the command.

Step 2: Set Up AWS CLI for LocalStack

Install AWS CLI:

brew install awscli

Note: The above command is for macOS. Find a complete documentation on how to install awscli.

Configure AWS CLI (necessary for LocalStack usage):

aws configure

Use placeholder values:

AWS Access Key ID: test
AWS Secret Access Key: test
Region: us-east-1
Output format: json
Set LocalStack Endpoint URL:

export LOCALSTACK_ENDPOINT=http://localhost:4566

Step 3: Create an S3 Bucket in LocalStack

To create a new S3 bucket:

aws --endpoint-url=$LOCALSTACK_ENDPOINT s3 mb s3://my-local-bucket

Step 4: Verify the Bucket

Check your bucket by listing all buckets:

aws --endpoint-url=$LOCALSTACK_ENDPOINT s3 ls

Step 5: Upload and Download Files

Create a sample file:

echo "Hello LocalStack!" > testfile.txt

Upload the file to your bucket:

aws --endpoint-url=$LOCALSTACK_ENDPOINT s3 cp testfile.txt s3://my-local-bucket

Download the file:

aws --endpoint-url=$LOCALSTACK_ENDPOINT s3 cp s3://my-local-bucket/testfile.txt downloaded_testfile.txt

Step 6: Use Python and Boto3 for S3 Operations

Install Boto3

pip install boto3

Python Code for Bucket Operations The following Python script demonstrates creating a bucket, uploading a file, listing objects, and downloading a file using Boto3:

import boto3
from botocore.config import Config

# Configuration for LocalStack
localstack_config = Config(
    region_name='us-east-1',
    retries={'max_attempts': 10, 'mode': 'standard'}
)

# Initialize the S3 client with LocalStack endpoint
s3_client = boto3.client(
    's3',
    endpoint_url="http://localhost:4566",
    aws_access_key_id="test",
    aws_secret_access_key="test",
    config=localstack_config
)

bucket_name = "my-local-bucket"

# Create the bucket
s3_client.create_bucket(Bucket=bucket_name)
print(f"Bucket '{bucket_name}' created.")

# Upload a file
s3_client.upload_file("testfile.txt", bucket_name, "testfile.txt")
print("File uploaded.")

# List objects in the bucket
objects = s3_client.list_objects_v2(Bucket=bucket_name)
for obj in objects.get('Contents', []):
    print("Found file:", obj['Key'])

# Download the file
s3_client.download_file(bucket_name, "testfile.txt", "downloaded_testfile.txt")
print("File downloaded.")

Run the script:

python your_script.py

Step 7: Clean Up Resources

To delete the bucket and its contents:

aws --endpoint-url=$LOCALSTACK_ENDPOINT s3 rb s3://my-local-bucket --force

Conclusion

This article provided a step-by-step walkthrough for setting up an S3 bucket in LocalStack. This setup is ideal for local development, allowing you to test AWS S3 functionality safely without incurring costs or needing an internet connection.

Blog