Documentation

How it works

MiniStack runs as a single ASGI process on one port (default 4566). Every AWS service shares that port. Requests are routed to the correct service handler based on:

• The Authorization header's credential scope (e.g. s3, dynamodb, ec2)
• The X-Amz-Target header (for JSON services like DynamoDB, SFN, EventBridge)
• The URL path (for REST services like S3, Route53, API Gateway)

You point any AWS SDK, CLI, or IaC tool to http://localhost:4566 with any credentials. MiniStack doesn't validate credentials — any access key works.

aws --endpoint-url=http://localhost:4566 s3 ls

Configuration

All configuration is via environment variables. Pass them to the Docker container or export them before running the process.

General

Persistence

Infrastructure services

Lambda

Nested containers (RDS / EKS / ElastiCache / Lambda)

Other

Persistence

MiniStack has three independent persistence layers. They don't depend on each other — enable whichever you need.

1. Service state (PERSIST_STATE=1)

Saves the metadata of all services (which queues exist, which Lambda functions are deployed, which DynamoDB tables, etc.) to JSON files in STATE_DIR. On next startup, everything is restored — your queues, functions, and tables are still there.

Does NOT save: S3 object bytes, RDS database data, or in-flight messages.

2. S3 objects (S3_PERSIST=1)

Saves actual file contents (the bytes you PUT into S3) to S3_DATA_DIR. Without this, object data lives only in memory.

3. Database data (RDS_PERSIST=1)

Switches RDS containers from tmpfs (RAM disk, ephemeral) to Docker named volumes (disk-backed, persistent). Your Postgres/MySQL data survives container restarts and has no fixed size cap.

Real infrastructure

Most services are in-memory emulations. These four actually spin up real processes:

RDS — Real Postgres/MySQL

CreateDBInstance pulls and starts a Docker container (postgres:15 or mysql:8). You get a real database on a real port. Connect with psycopg2, mysql-connector, DBeaver — anything.

# After creating the instance:
psql -h localhost -p 15432 -U admin -d mydb

ElastiCache — Real Redis

CreateCacheCluster starts a real Redis container. Use any Redis client. Pub/sub works, Lua scripts work, everything works.

redis-cli -p 16379
127.0.0.1:16379> SET hello world
OK

ECS — Real Docker containers

RunTask pulls and runs the image from your task definition. Real containers on your Docker socket.

Lambda — Real code execution

Lambda functions actually execute. Python functions run as subprocesses (or in Docker containers if LAMBDA_EXECUTOR=docker). Your handler code runs, returns a response, and can call other MiniStack services.

Testcontainers

MiniStack ships official Testcontainers modules for both Java and Python. They spin up ministackorg/ministack on a random host port, wait for /_ministack/health, and hand your test the endpoint URL + credentials.

Java

<dependency>
  <groupId>org.ministack</groupId>
  <artifactId>testcontainers-ministack</artifactId>
  <version>0.1.4</version>
  <scope>test</scope>
</dependency>

try (MiniStackContainer ms = new MiniStackContainer()) {
    ms.start();
    S3Client s3 = S3Client.builder()
        .endpointOverride(URI.create(ms.getEndpoint()))
        .region(Region.of(ms.getRegion()))
        .credentialsProvider(StaticCredentialsProvider.create(
            AwsBasicCredentials.create(ms.getAccessKey(), ms.getSecretKey())))
        .build();
    // ... your test
}

Real-infrastructure mode

withRealInfrastructure() mounts the host's Docker socket so RDS, ElastiCache, ECS, and EKS spin up real sidecar containers during the test. The stop() override reaps every MiniStack-labelled container and volume on the host engine — no leaks under Docker or Podman.

try (MiniStackContainer ms = new MiniStackContainer().withRealInfrastructure()) {
    ms.start();
    // CreateDBInstance will spin up a real postgres container
}

Private-registry setup

Set Testcontainers' hub.image.name.prefix in ~/.testcontainers.properties (or via the TESTCONTAINERS_HUB_IMAGE_NAME_PREFIX env var) and every nested image — the MiniStack image itself, the postgres/redis/k3s sidecars, and Lambda runtimes under public.ecr.aws/lambda/* — routes through your registry mirror. The Java module forwards the prefix into MINISTACK_IMAGE_PREFIX automatically.

Errors

MiniStack returns errors in the same format as AWS — XML for Query/XML services, JSON for JSON services. Status codes match AWS behavior.

Common errors you'll see

Health check

Hit GET /_ministack/health to verify the server is running. Returns 200 with service status.

curl http://localhost:4566/_ministack/health

Differences from AWS

MiniStack emulates API behavior, not infrastructure. Here's what that means:

No IAM enforcement

All API calls succeed regardless of the IAM policies attached to the caller. IAM resources (users, roles, policies) are stored but never evaluated. Any access key/secret key works.

No real networking

EC2 instances, VPCs, subnets, and security groups exist as metadata. You can't SSH into an instance or route traffic between subnets. These resources exist so Terraform/CDK plans succeed — not to provide real network isolation.

No scheduled execution

EventBridge scheduled rules and cron expressions are stored but never automatically triggered. To test event-driven flows, use PutEvents manually.

Multi-region

MiniStack honors per-request regions. A caller signing with us-east-1 and another signing with eu-west-1 get responses with region-correct ARNs and endpoints — the region is derived from the caller's SigV4 credential scope, not a single server-wide setting. MINISTACK_REGION sets the default for unsigned callers. State is scoped per account; some regional services share the underlying store across regions, so use unique resource names if you exercise two regions from the same account.

CloudFront is metadata-only

Distributions are stored and returned via API, but there's no actual edge caching or content delivery.

EMR/Glue jobs don't execute

Job metadata is tracked but no Spark or Hadoop processing occurs. Useful for testing IaC and orchestration, not for testing data pipelines.

Timestamps

Some services return epoch floats (for Go/Terraform SDK compatibility) where AWS returns ISO strings. This was an intentional choice to maximize compatibility across SDKs.

Account ID

Default account ID is 000000000000. ARNs use this account. Some SDKs send empty account IDs — MiniStack normalizes these automatically.

IaC setup

Terraform

Compatible with AWS Provider v5 and v6. Add endpoint overrides:

provider "aws" {
  region                      = "us-east-1"
  access_key                  = "test"
  secret_key                  = "test"
  s3_use_path_style           = true
  skip_credentials_validation = true
  skip_metadata_api_check     = true
  skip_requesting_account_id  = true

  endpoints {
    s3             = "http://localhost:4566"
    dynamodb       = "http://localhost:4566"
    sqs            = "http://localhost:4566"
    sns            = "http://localhost:4566"
    lambda         = "http://localhost:4566"
    iam            = "http://localhost:4566"
    ec2            = "http://localhost:4566"
    ecs            = "http://localhost:4566"
    cloudformation = "http://localhost:4566"
    route53        = "http://localhost:4566"
    cloudwatch     = "http://localhost:4566"
    secretsmanager = "http://localhost:4566"
    ssm            = "http://localhost:4566"
    kms            = "http://localhost:4566"
    rds            = "http://localhost:4566"
    sts            = "http://localhost:4566"
  }
}

CDK

Use the cdklocal wrapper. It points all CDK operations to localhost:4566:

npm install -g aws-cdk-local
cdklocal bootstrap
cdklocal deploy

Pulumi

Configure endpoint overrides in Pulumi.dev.yaml:

config:
  aws:region: us-east-1
  aws:accessKey: test
  aws:secretKey: test
  aws:s3UsePathStyle: true
  aws:skipCredentialsValidation: true
  aws:skipMetadataApiCheck: true
  aws:skipRequestingAccountId: true
  aws:endpoints:
    - s3: http://localhost:4566
      dynamodb: http://localhost:4566
      sqs: http://localhost:4566
      lambda: http://localhost:4566

CloudFormation

MiniStack has a built-in CloudFormation engine that supports 66 resource types. Deploy stacks directly via the API:

aws --endpoint-url=http://localhost:4566 cloudformation create-stack \
  --stack-name my-stack \
  --template-body file://template.yaml

Docker Compose

A ready-to-use setup with full persistence and Lambda Docker support:

services:
  ministack:
    image: ministackorg/ministack:latest
    ports:
      - "4566:4566"
    environment:
      - PERSIST_STATE=1
      - S3_PERSIST=1
      - RDS_PERSIST=1
      - LOG_LEVEL=INFO
      - LAMBDA_EXECUTOR=docker
      - LAMBDA_DOCKER_NETWORK=myproject_default
    volumes:
      - ./data/state:/tmp/ministack-state
      - ./data/s3:/tmp/ministack-data/s3
      - /var/run/docker.sock:/var/run/docker.sock
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:4566/_ministack/health')"]
      interval: 10s
      timeout: 3s
      retries: 3