LocalStack Deployment and Usage Guide

Prerequisites

Before installing LocalStack, ensure you have the following tools installed on your system:

• make - Build automation tool
• python - Both Python 2.x and 3.x are supported
• pip - Python package manager
• npm - Node.js package manager
• java/javac - Java 8 runtime environment and compiler
• mvn - Maven build system for Java

Installation

Using pip (Recommended)

The easiest way to install LocalStack is via pip:

pip install localstack

From Source

If you prefer to install from source, follow these steps:

1. Clone the repository from the new maintained location:

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

2. Install the package:

make install

Important Note: Do not use sudo or the root user when installing LocalStack. It should be installed entirely under a local non-root user.

Configuration

Environment Variables

You can configure LocalStack using the following environment variables:

• SERVICES: Comma-separated list of service names and optional ports they should run on. Example: kinesis,lambda:4569,sqs:4570

AWS Credentials

LocalStack uses AWS credentials for compatibility with AWS SDKs. You can set these environment variables:

export AWS_ACCESS_KEY_ID=foobar
export AWS_SECRET_ACCESS_KEY=foobar
export AWS_DEFAULT_REGION=us-east-1

Service Configuration

LocalStack spins up the following core AWS APIs on your local machine:

• API Gateway at http://localhost:4567
• Kinesis at http://localhost:4568
• DynamoDB at http://localhost:4569
• DynamoDB Streams at http://localhost:4570
• Elasticsearch at http://localhost:4571
• S3 at http://localhost:4572
• Firehose at http://localhost:4573
• Lambda at http://localhost:4574
• SNS at http://localhost:4575
• SQS at http://localhost:4576
• Redshift at http://localhost:4577
• ES (Elasticsearch Service) at http://localhost:4578
• SES at http://localhost:4579
• Route53 at http://localhost:4580
• CloudFormation at http://localhost:4581
• CloudWatch at http://localhost:4582

Build & Run

Starting LocalStack

After installation, start the infrastructure using:

localstack start

Running in Docker

You can also run LocalStack in Docker:

localstack start --docker

Or using docker-compose (after cloning the repository):

docker-compose up

Note for MacOS users: If $TMPDIR contains a symbolic link that cannot be mounted by Docker, run:

TMPDIR=/private$TMPDIR docker-compose up

Development Mode

For development, you can run LocalStack with additional debugging options:

DEBUG=1 localstack start

Deployment

LocalStack is primarily designed as a local development and testing tool. However, if you need to deploy it for team use or CI/CD pipelines, consider these options:

Docker Deployment

The Docker approach is recommended for deployment:

1. Create a Dockerfile:

FROM localstack/localstack

2. Build and run:

docker build -t my-localstack .
docker run -p 4567-4592:4567-4592 my-localstack

Kubernetes Deployment

For Kubernetes environments, you can deploy LocalStack as a pod:

apiVersion: v1
kind: Pod
metadata:
  name: localstack
spec:
  containers:
  - name: localstack
    image: localstack/localstack
    ports:
    - containerPort: 4567
    - containerPort: 4568
    # ... other ports

Troubleshooting

Common Issues and Solutions

Port Conflicts

Issue: LocalStack fails to start because ports are already in use.

Solution: Either stop the conflicting service or specify alternative ports using the SERVICES environment variable.

export SERVICES=kinesis:4569,lambda:4570,sqs:4571

Permission Issues

Issue: Installation or startup fails due to permission errors.

Solution: Ensure you're not using sudo or running as root. LocalStack should be installed and run as a regular user.

Java Dependencies

Issue: Lambda functions with Java runtime fail due to missing dependencies.

Solution: Ensure Java 8 is installed and the JAVA_HOME environment variable is set correctly.

Python Dependencies

Issue: Python-based services fail to start.

Solution: Verify that Python and pip are installed correctly. You may need to install additional dependencies:

pip install boto3

Docker Volume Issues on MacOS

Issue: Docker volume mounting fails on MacOS.

Solution: Use the temporary directory workaround:

TMPDIR=/private$TMPDIR docker-compose up

Service-Specific Issues

For service-specific problems, check the logs by running LocalStack with debug mode:

DEBUG=1 localstack start

Network Connectivity

Issue: Services cannot communicate with each other.

Solution: Ensure your firewall allows connections on the LocalStack ports (4567-4592).

Lambda Function Execution

Issue: Lambda functions fail to execute.

Solution: Check that the Lambda runtime (Python, Node.js, or Java) is properly installed and configured. For Java functions, ensure the Maven dependencies are available in the local repository.

Getting Help

For additional support, refer to the new maintained repository:

• Repository: https://github.com/localstack/localstack
• Issues: https://github.com/localstack/localstack/issues

Remember that this repository is no longer actively maintained, so please direct any issues or contributions to the new location.