LocalStack S3 Mock

A local AWS S3 simulation service for the Melodia music streaming platform using LocalStack. This service provides S3-compatible storage for development and testing without requiring actual AWS infrastructure.

Table of Contents

• Overview
• Getting Started
• Project Structure
• Useful Commands
• Troubleshooting

Overview

LocalStack simulates AWS S3 services locally, enabling microservices to interact with cloud storage during development without AWS credentials or costs. This setup provides:

• S3 Bucket Management: Automatic bucket creation and configuration
• File Storage: Store and retrieve files (images, audio, documents)
• Network Integration: Seamless connection with Melodia microservices via Docker network

Storage Structure

melodiapp-dev-bucket/
├── profile-pictures/      # User profile images (Users Service)
└── artists/               # Artist-related files (Artists Service)
    ├── avatars/           # Artist profile pictures
    ├── albums-pictures/   # Album cover images
    └── songs-pictures/    # Song cover images

Key Features

• Automatic bucket initialization on startup
• S3-compatible API endpoints
• Docker network integration with melodiapp-net
• Default credentials (test/test) for development
• Health check monitoring

Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

• Docker - Download
• Docker Compose - Included with Docker Desktop

1. Clone the Repository

git clone https://github.com/MelodiApp/localstack.git
cd localstack

2. Environment Setup

Copy the example environment file and configure your LocalStack Pro token:

cp .env.example .env

Edit the .env file and add your LocalStack Pro authentication token:

LOCALSTACK_AUTH_TOKEN=your-localstack-token-here

You can get your token from the LocalStack dashboard.

3. Create Docker Network

The LocalStack service requires a shared Docker network to communicate with other Melodia microservices:

docker network create melodiapp-net

4. Start LocalStack

Start the LocalStack service using Docker Compose:

docker compose up -d

The S3 service will be available at:

• From containers: http://localstack:4566
• From host machine: http://localhost:4566

5. Verify Installation

Check that LocalStack is running correctly:

# Check container status
docker ps | grep localstack

# Verify service health
curl http://localhost:4566/health

# List S3 buckets (should show melodiapp-dev-bucket)
docker exec -it localstack-s3-mock awslocal s3 ls

# View bucket contents
docker exec -it localstack-s3-mock awslocal s3 ls s3://melodiapp-dev-bucket/

Expected output:

{"s3": "running"}

Configuration

LocalStack works with default configuration values. The only configurable environment variables in .env are:

Variable	Default Value	Description
DEBUG	0	Enable debug logging (0 or 1)
LOCALSTACK_AUTH_TOKEN	Required	LocalStack Pro license token
LOCALSTACK_VOLUME_DIR	./volume	Directory for persistent data

The following values are hardcoded and do not need configuration:

Variable	Value	Description
AWS_ACCESS_KEY_ID	test	Mock access key
AWS_SECRET_ACCESS_KEY	test	Mock secret key
AWS_DEFAULT_REGION	us-east-1	AWS region
Bucket name	melodiapp-dev-bucket	S3 bucket name
S3 endpoint (internal)	http://localstack:4566	From Docker containers
S3 endpoint (external)	http://localhost:4566	From host machine

Microservices automatically detect the development environment and use these values.

Automatic Initialization

The init-scripts/01-setup-s3.sh script runs automatically when LocalStack starts and performs the following:

1. Creates the melodiapp-dev-bucket bucket
2. Configures CORS policies for web access
3. Creates the directory structure for organized file storage

Useful Commands

Service Management

# Start LocalStack
docker compose up -d

# View logs in real-time
docker compose logs -f

# Stop LocalStack (preserves data in memory)
docker compose stop

# Start after stopping
docker compose start

# Stop and remove containers (removes all data)
docker compose down

# Remove all data including volumes
docker compose down -v

S3 Operations

Access the LocalStack container to run S3 commands:

# Access container shell
docker exec -it localstack-s3-mock bash

# Inside the container, use awslocal commands:

# List all buckets
awslocal s3 ls

# List bucket contents recursively
awslocal s3 ls s3://melodiapp-dev-bucket/ --recursive

# Upload a file
awslocal s3 cp file.txt s3://melodiapp-dev-bucket/test/

# Download a file
awslocal s3 cp s3://melodiapp-dev-bucket/test/file.txt downloaded.txt

# Delete a file
awslocal s3 rm s3://melodiapp-dev-bucket/test/file.txt

Health Checks

# Check LocalStack health
curl http://localhost:4566/health

# Check detailed service status
curl http://localhost:4566/_localstack/health

# Verify bucket accessibility
curl http://localhost:4566/melodiapp-dev-bucket/

Troubleshooting

LocalStack doesn't start

Issue: Container fails to start or exits immediately.

Solution:

# Verify Docker is running
docker info

# Check if port 4566 is available
lsof -i :4566

# View error logs
docker compose logs localstack

Network not found

Issue: Error about melodiapp-net network not existing.

Solution:

# Create the network
docker network create melodiapp-net

# Verify network exists
docker network ls | grep melodiapp-net

Bucket not created automatically

Issue: melodiapp-dev-bucket doesn't exist after startup.

Solution:

# Check initialization logs
docker compose logs localstack | grep "setup-s3"

# Create bucket manually if needed
docker exec -it localstack-s3-mock awslocal s3 mb s3://melodiapp-dev-bucket

Microservices cannot connect

Issue: Other services cannot reach LocalStack.

Solution:

# Verify both containers are on the same network
docker network inspect melodiapp-net

# Test connectivity from another container
docker exec -it <microservice-container> ping localstack

# Verify LocalStack is accessible
docker exec -it <microservice-container> curl http://localstack:4566/health

Related Services

• Artists Microservice - Manages artist profiles, songs, and albums
• Users Microservice - Handles user authentication and profile management
• Libraries Service - Manages user playlists and saved content
• Metrics Service - Handles play counts and analytics
• Notifications Service - Sends notifications for new releases
• API Gateway - Centralized API routing and authentication
• Mobile Frontend - Melodia mobile application
• Web Frontend - Melodia backoffice application