Migrating from LocalStack to fakecloud in 10 minutes

Canonical: fakecloud.dev/blog/migrate-from-localstack

In March 2026, LocalStack replaced its open-source Community Edition with a proprietary image that requires an account and an auth token. If your build broke last month, this guide is for you. If you are still on a pinned older tag and worried about the next pull, this is also for you.

fakecloud is a free, open-source AWS emulator — single binary, no account, no token, no paid tier — that covers the services most teams relied on LocalStack Community for, plus several that moved to LocalStack Pro (RDS, ElastiCache, Cognito User Pools, SES v2, API Gateway v2).

This guide is step-by-step. Copy, paste, done.

The one-line summary

Change the image or the install command. Keep http://localhost:4566 and your dummy credentials. Everything else stays the same.

Step 1: Stop LocalStack

docker compose down
# or: docker kill $(docker ps -q --filter ancestor=localstack/localstack)

Step 2: Install fakecloud

# Option A: single binary, no Docker
curl -fsSL https://raw.githubusercontent.com/faiscadev/fakecloud/main/install.sh | bash
fakecloud

# Option B: Docker
docker run --rm -p 4566:4566 ghcr.io/faiscadev/fakecloud

# Option C: cargo
cargo install fakecloud

fakecloud listens on http://localhost:4566 — same as LocalStack.

Step 3: Keep your SDK wiring

Your application code does not change. Endpoint URL and dummy credentials stay identical:

// TypeScript
import { S3Client } from "@aws-sdk/client-s3";
const s3 = new S3Client({
  endpoint: "http://localhost:4566",
  region: "us-east-1",
  credentials: { accessKeyId: "test", secretAccessKey: "test" },
  forcePathStyle: true,
});

# Python (boto3)
import boto3
s3 = boto3.client(
    "s3",
    endpoint_url="http://localhost:4566",
    aws_access_key_id="test",
    aws_secret_access_key="test",
    region_name="us-east-1",
)

Step 4: Update docker-compose.yml

Before:

services:
  localstack:
    image: localstack/localstack:latest
    ports:
      - "4566:4566"
    environment:
      - SERVICES=s3,sqs,sns,dynamodb,lambda
      - DEBUG=1

After:

services:
  fakecloud:
    image: ghcr.io/faiscadev/fakecloud:latest
    ports:
      - "4566:4566"

fakecloud starts all services by default (they are lazy and cheap — no SERVICES env var needed).

For Lambda execution you will need Docker-in-Docker or a mounted Docker socket (same as LocalStack Pro required):

services:
  fakecloud:
    image: ghcr.io/faiscadev/fakecloud:latest
    ports:
      - "4566:4566"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

Step 5: Update GitHub Actions

Before:

services:
  localstack:
    image: localstack/localstack
    ports:
      - 4566:4566
    env:
      LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_TOKEN }}

After (install-and-run, no Docker):

steps:
  - run: curl -fsSL https://raw.githubusercontent.com/faiscadev/fakecloud/main/install.sh | bash
  - run: fakecloud &
  - run: |
      for i in $(seq 1 30); do
        curl -sf http://localhost:4566/_fakecloud/health && exit 0
        sleep 1
      done
      exit 1

~500ms startup vs ~3s for LocalStack container boot. On a cold CI runner the difference adds up over hundreds of test runs.

Step 6: Terraform

Provider block stays the same — only the running emulator changes.

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

  endpoints {
    s3       = "http://localhost:4566"
    sqs      = "http://localhost:4566"
    dynamodb = "http://localhost:4566"
    lambda   = "http://localhost:4566"
  }
}

fakecloud's CI runs the upstream hashicorp/terraform-provider-aws TestAcc* suites against itself, so Terraform flows that worked against LocalStack Community should work against fakecloud.

Things that may need attention

SERVICES env var. Drop it. fakecloud starts all services by default.
LOCALSTACK_AUTH_TOKEN. Drop it.
Persisted state. LocalStack Pro has PERSISTENCE=1. fakecloud has --persist /path/to/dir.

Services that moved from LocalStack Community to Pro (and what fakecloud does)

Service	LocalStack Community now	fakecloud
Cognito User Pools	Paid only	122 ops, full auth flows + MFA
SES v2	Paid only	110 ops, full send + templates + DKIM
API Gateway v2	Paid only	28 ops, HTTP APIs + JWT/Lambda authorizers
RDS	Paid only	163 ops, real PostgreSQL/MySQL/MariaDB via Docker
ElastiCache	Paid only	75 ops, real Redis/Valkey via Docker
Bedrock	Not available	111 ops (control plane + runtime)

Test-assertion SDKs (bonus)

fakecloud ships test-assertion SDKs that let you inspect side effects from tests without raw HTTP:

import { FakeCloud } from "fakecloud";
const fc = new FakeCloud();

const { emails } = await fc.ses.getEmails();
expect(emails).toHaveLength(1);
expect(emails[0].destination.toAddresses).toContain("alice@example.com");

await fc.reset();

SDKs for TypeScript, Python, Go, PHP, Java, Rust. See the SDK docs.

Verify the migration

aws --endpoint-url http://localhost:4566 s3 mb s3://test-bucket
echo hello | aws --endpoint-url http://localhost:4566 s3 cp - s3://test-bucket/hello.txt
aws --endpoint-url http://localhost:4566 s3 ls s3://test-bucket/
aws --endpoint-url http://localhost:4566 s3 rb s3://test-bucket --force

If it works, migration is done.

推荐订阅源

DEV Community