LocalStack

Overview

LocalStack is a local AWS cloud emulator that runs in a Docker container on your machine. It provides functional implementations of AWS services like DynamoDB, S3, and Cognito, allowing you to develop and test without connecting to a real AWS account or incurring cloud costs.

Stackpane supports connecting to LocalStack as a drop-in replacement for AWS. All DynamoDB, S3, and Cognito operations work the same way — you browse tables, manage users, and upload files using the same interface.

Prerequisites

Before connecting Stackpane to LocalStack, you need:

1. Docker — LocalStack runs as a Docker container. Install Docker Desktop if you have not already.
2. LocalStack — Install and start LocalStack using one of the methods below.

Starting LocalStack with Docker

The simplest way to run LocalStack:

docker run --rm -p 4566:4566 -p 4510-4559:4510-4559 localstack/localstack

This starts LocalStack with all supported services on port 4566.

Starting LocalStack with Docker Compose

For a reproducible team setup, add LocalStack to your docker-compose.yml:

services:
  localstack:
    image: localstack/localstack
    ports:
      - "4566:4566"
      - "4510-4559:4510-4559"
    environment:
      - SERVICES=dynamodb,s3,cognito-idp

Run docker compose up to start the services.

Starting LocalStack with the CLI

If you have the LocalStack CLI installed:

localstack start

Connecting Stackpane to LocalStack

1. Click the + button in the sidebar or choose New Connection.
2. Select AWS as the provider.
3. Enter a connection name (e.g., “Local Development”).
4. For Access Key ID and Secret Access Key, enter any non-empty value (e.g., test / test). LocalStack does not validate credentials by default.
5. Select any region (e.g., us-east-1). LocalStack accepts all regions.
6. Enter the custom endpoint URL: http://localhost:4566.
7. Click Save.

Stackpane routes all API calls to the LocalStack endpoint instead of AWS.

Supported Services

Stackpane supports the following services through LocalStack:

DynamoDB

Full support for all DynamoDB operations:

• Create, scan, query, and delete tables
• GetItem, PutItem, UpdateItem, DeleteItem
• BatchWriteItem for bulk operations
• Table metadata and key schema inspection

S3

Full support for all S3 operations:

• Bucket listing and object browsing
• Upload, download, and delete objects
• Copy objects and manage metadata
• Virtual folder navigation

Cognito User Pools

Full support for user management:

• List and inspect users
• Create, edit, and delete users
• Disable/enable accounts and reset passwords
• Revoke sessions

Creating Test Data

LocalStack starts with empty services. You can create test data directly from Stackpane:

1. DynamoDB: Use the AWS CLI or Stackpane’s item creation interface to add tables and items.
2. S3: Upload files through Stackpane’s S3 browser or use the AWS CLI with --endpoint-url http://localhost:4566.
3. Cognito: Create user pools and users through Stackpane or the AWS CLI.

Using the AWS CLI with LocalStack

You can use the standard AWS CLI to set up test data by adding the --endpoint-url flag:

# Create a DynamoDB table
aws dynamodb create-table \
  --table-name Users \
  --attribute-definitions AttributeName=userId,AttributeType=S \
  --key-schema AttributeName=userId,KeyType=HASH \
  --billing-mode PAY_PER_REQUEST \
  --endpoint-url http://localhost:4566

# Create an S3 bucket
aws s3 mb s3://my-bucket --endpoint-url http://localhost:4566

# Create a Cognito user pool
aws cognito-idp create-user-pool \
  --pool-name TestPool \
  --endpoint-url http://localhost:4566

After creating resources with the CLI, click Refresh in Stackpane to see them.

Differences from Production AWS

While LocalStack provides a faithful emulation of AWS services, there are some differences to be aware of:

• No authentication enforcement — LocalStack accepts any credentials by default. IAM policies are not evaluated.
• Data persistence — By default, LocalStack data is lost when the container stops. Use the PERSISTENCE=1 environment variable or mount a volume to persist data across restarts.
• Feature parity — Some advanced DynamoDB features (like DynamoDB Streams, Global Tables, or DAX) may not be fully implemented in LocalStack.
• Performance characteristics — Local execution does not reflect real-world latency or throughput limits.
• S3 region handling — LocalStack serves all buckets from the same endpoint regardless of region.

Limitations

• LocalStack Community edition supports DynamoDB, S3, and Cognito. Some advanced features may require LocalStack Pro.
• Stackpane connects to a single LocalStack endpoint per connection. If you run multiple LocalStack instances, create a separate connection for each.
• Data created in LocalStack is not synchronized with AWS. Use LocalStack for development and testing, then deploy to your real AWS account.

Tips

• Keep a docker-compose.yml in your project repository so the entire team uses the same LocalStack configuration
• Use seed scripts to populate LocalStack with test data on startup
• Create separate Stackpane connections for LocalStack and production AWS to avoid confusion — use distinct connection names like “Local Dev” and “Production”
• If LocalStack fails to start, verify that port 4566 is not in use by another process