LocalStack CLI (Python Package)

Warnings

• gotcha The `localstack` Python package primarily provides the CLI. For interacting with AWS services running on LocalStack, you should use `boto3` (or other AWS SDKs) and configure the `endpoint_url` to point to your LocalStack instance (e.g., `http://localhost:4566`).
  Fix: When creating `boto3` clients, always specify `endpoint_url` (e.g., `boto3.client('s3', endpoint_url='http://localhost:4566')`). Ensure `aws_access_key_id` and `aws_secret_access_key` are set to dummy values like 'test' if not using explicit credentials.
• breaking LocalStack's versioning scheme changed from semantic versioning (e.g., `1.x.y`) to calendar-based versioning (e.g., `YYYY.M.D`). Be mindful of this when checking for compatibility or specific feature availability.
  Fix: Always refer to the latest documentation for features and breaking changes relative to the current calendar version. Update your `pip install localstack` commands to pin to specific calendar versions if needed (e.g., `localstack==2023.1.0`).
• deprecated Several configuration environment variables have been renamed or deprecated over time. A notable example is `LOCALSTACK_HOST`, which was deprecated in favor of `LS_HOST`.
  Fix: Always consult the official LocalStack configuration documentation (docs.localstack.cloud/references/configuration/) for the most up-to-date environment variable names and their usage. Update your environment variables or `docker-compose` files accordingly.
• gotcha Persistence is not enabled by default. If LocalStack restarts without persistence configured, all your data (e.g., S3 buckets, DynamoDB tables) will be lost.
  Fix: To enable persistence, set the `DATA_DIR` environment variable to a host directory where LocalStack can store its data (e.g., `DATA_DIR=/tmp/localstack/data`). This is typically done via `docker-compose.yaml` or as an environment variable when running `localstack start`.
• gotcha LocalStack requires Docker to be running on your system. It relies heavily on Docker containers for providing its emulated services. Without Docker, `localstack start` will fail.
  Fix: Ensure Docker Desktop or Docker Engine is installed and running before attempting to start LocalStack. Troubleshoot Docker issues independently if LocalStack fails to start.

Install

• pip install localstack Install LocalStack CLI

Imports

• main

  from localstack.main import main

  This import is for programmatically invoking the LocalStack CLI entry point (e.g., in advanced automation scripts). For interacting with AWS services running on LocalStack, `boto3` (configured with `endpoint_url`) is the standard method, not this package directly.
• boto3.client

  import boto3; client = boto3.client('s3', endpoint_url='http://localhost:4566')

  While `boto3` is not part of the `localstack` package, it's the primary way Python developers interact with AWS services provided by LocalStack. The `endpoint_url` is crucial to direct `boto3` calls to your local LocalStack instance.

Quickstart

This quickstart demonstrates how to programmatically start LocalStack using its CLI via `subprocess`, wait for it to initialize, and then interact with a mocked AWS S3 service using `boto3`. It's important to have Docker running in the background for LocalStack to function.

import subprocess
import time
import os
import boto3

def start_localstack():
    print('Starting LocalStack in the background...')
    # Use subprocess to run 'localstack start' non-blocking
    # Note: Requires 'localstack' CLI to be in PATH
    process = subprocess.Popen(['localstack', 'start'], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
    # Give LocalStack some time to start up
    time.sleep(15) 
    # Check if LocalStack is running via 'localstack status'
    status_output = subprocess.run(['localstack', 'status'], capture_output=True, text=True)
    if 'running' in status_output.stdout:
        print('LocalStack is running.')
    else:
        print('LocalStack failed to start or is not running correctly.')
        print('STDOUT:', status_output.stdout)
        print('STDERR:', status_output.stderr)
        # Optionally, terminate the Popen process if it didn't start correctly
        # process.terminate()
        # return None
    return process

def stop_localstack(process):
    print('Stopping LocalStack...')
    subprocess.run(['localstack', 'stop'])
    if process: # Terminate the Popen process if it was started this way
        process.terminate()
        process.wait()
    print('LocalStack stopped.')

def main():
    localstack_process = None
    try:
        localstack_process = start_localstack()
        if not localstack_process:
            return

        # Now, interact with a service (e.g., S3) using boto3
        print('\nInteracting with S3 on LocalStack...')
        s3_client = boto3.client(
            's3',
            region_name='us-east-1',
            endpoint_url='http://localhost:4566',
            aws_access_key_id='test',
            aws_secret_access_key='test'
        )

        bucket_name = 'my-local-test-bucket'
        try:
            s3_client.create_bucket(Bucket=bucket_name)
            print(f"Bucket '{bucket_name}' created successfully.")

            response = s3_client.list_buckets()
            print('Existing buckets:')
            for bucket in response['Buckets']:
                print(f"  - {bucket['Name']}")

        except Exception as e:
            print(f"Error interacting with S3: {e}")

    finally:
        stop_localstack(localstack_process)

if __name__ == '__main__':
    # Ensure Docker is running before executing this script
    # On first run, 'localstack start' will download necessary Docker images.
    main()