LocalStack 과 MiniStack — 로컬에서 AWS 흉내내기

AWS 대부분은 인터넷 너머 마법의 데이터센터에서 돈을 받고 일합니다. 개발 머신에서 검증하려면 (1) 실제 AWS 에 PoC 계정 만들기, (2) 어딘가에 비용을 결제하기, (3) 인터넷이 죽으면 손이 멈추기 — 세 가지 비용을 매일 치러야 합니다. 로컬 에뮬레이터는 이 세 비용을 0 에 가깝게 만듭니다.

1. LocalStack 에 대한 이야기

LocalStack 은 가장 오래되고 검증된 AWS 에뮬레이터입니다 (2017~). LocalStack LLC (독일 베를린 · 미국 마운틴뷰) 가 운영하며, Community (무료, Apache 2.0) 와 Pro (유료) 두 에디션이 있습니다.

Community 에 포함:

• S3 · SQS · SNS · DynamoDB · Lambda · KMS · EventBridge · SES.

Pro 에 추가:

• IAM 정책 시뮬레이션.
• CloudFormation 의 거의 모든 리소스.
• EKS.

기본 게이트웨이 포트는 4566 (edge port).

2. MiniStack 에 대한 이야기

MiniStack 은 LocalStack 의 무료 대안으로 2025 년 등장했습니다. MIT 라이선스, 단일 컨테이너에 45+ AWS 서비스. 가장 큰 차별점은 "흉내내지 않고 진짜를 띄운다" 는 것:

• RDS 호출이 들어오면 진짜 Postgres 컨테이너 시작.
• ElastiCache 는 진짜 Redis.
• ECS 는 진짜 Docker 컨테이너.

이미지 ~270 MB / idle 메모리 ~21 MB 수준으로 가볍고, 시작이 2 초 내외로 빠릅니다. 게이트웨이 포트도 4566 (LocalStack 호환).

3. 어떻게 다른가

항목	LocalStack Community	MiniStack
라이선스	Apache 2.0	MIT
이미지 크기	~2.5 GB	~270 MB
Idle 메모리	~500 MB	~21 MB
시작 시간	30~60 초	< 2 초
핵심 동작	모든 서비스 mock	인프라성 서비스는 실제 컨테이너
서비스 커버리지	S3 · SQS · SNS · DynamoDB · Lambda · SES · KMS · EventBridge	45+ — RDS · ElastiCache · ECS · EKS · S3 · Lambda · SES
Pro 에디션	있음	없음
한국어 자료	많음	적음 (신생)

LocalStack 이 적합한 경우 — Lambda 인보크 시뮬레이션, SES 메일 라우팅 mock, KMS 키 정책, EventBridge rule, CloudFormation 검증처럼 mock 의 충실도가 더 중요할 때.

MiniStack 이 적합한 경우 — 로컬에서 RDS · ElastiCache · ECS 를 띄워 실제 연결성 확인, 메모리 빠듯한 노트북, drop-in LocalStack 호환 + 라이선스 단순화.

두 개를 동시에 띄우기 — 정상적인 패턴. MiniStack 으로 인프라 검증을, LocalStack 으로 mock 안정성이 중요한 서비스를 분리.

4. LocalStack 띄우기

# docker-compose.yml
services:
  localstack:
    image: localstack/localstack:3.8
    ports:
      - "4566:4566"
    environment:
      SERVICES: s3,ses,sqs,sns,dynamodb,lambda,kms,iam,sts
      PERSISTENCE: 1
      DOCKER_HOST: unix:///var/run/docker.sock
    volumes:
      - ./data:/var/lib/localstack
      - /var/run/docker.sock:/var/run/docker.sock

SERVICES 로 활성 서비스만 켜면 부팅이 빠릅니다. PERSISTENCE=1 이면 종료 후에도 자원이 살아남습니다. Lambda · ECS 처럼 다른 컨테이너를 띄워야 하는 서비스는 호스트 도커 소켓 마운트가 필수.

5. MiniStack 띄우기

services:
  ministack:
    image: ministackorg/ministack:latest
    ports:
      - "4566:4566"
    environment:
      GATEWAY_PORT: 4566
      S3_PERSIST: 1
      REDIS_HOST: redis
    volumes:
      - ./data:/tmp/ministack-data
      - /var/run/docker.sock:/var/run/docker.sock
    depends_on:
      redis:
        condition: service_healthy

  redis:
    image: redis:7-alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]

MiniStack 은 ElastiCache 가 "진짜" 라서 동반 Redis 가 필수입니다. RDS 도 호출이 들어오면 자체적으로 Postgres 컨테이너를 띄웁니다.

6. 호출하기

두 에뮬레이터 모두 endpoint 를 4566 으로 가리키기만 하면 표준 AWS SDK 가 그대로 동작합니다. 키는 아무 문자열 (관례적으로 test).

import boto3

s3 = boto3.client(
    "s3",
    endpoint_url="http://localhost:4566",
    region_name="ap-northeast-2",
    aws_access_key_id="test",
    aws_secret_access_key="test",
)
s3.create_bucket(Bucket="my-bucket")
s3.put_object(Bucket="my-bucket", Key="hello.txt", Body=b"world")

const s3 = new S3Client({
  endpoint: "http://localhost:4566",
  region: "ap-northeast-2",
  credentials: { accessKeyId: "test", secretAccessKey: "test" },
  forcePathStyle: true,
});

export AWS_ENDPOINT_URL=http://localhost:4566
export AWS_ACCESS_KEY_ID=test
export AWS_SECRET_ACCESS_KEY=test
aws s3 ls

LocalStack 컨테이너 안에는 awslocal 이라는 wrapper 가 있어서 endpoint 지정을 생략할 수 있습니다.

7. 동시 운용 — 포트 충돌 회피

둘 다 디폴트가 4566 이므로 한 머신에서 같이 띄우려면 한쪽 호스트 포트를 시프트합니다. 컨테이너 내부 포트는 그대로 둬야 SDK 호환이 깨지지 않습니다.

# LocalStack 만 4666 으로 시프트
ports:
  - "4666:4566"

ministack = boto3.client("s3", endpoint_url="http://localhost:4566", ...)
localstack = boto3.client("ses", endpoint_url="http://localhost:4666", ...)

8. 한계

AWS 의 모든 동작과 1:1 같지 않습니다 — IAM 권한 평가 · Role assume · KMS 키 정책에서 미묘한 차이. 본 운용 전 실제 AWS 에서 한 번은 검증해야 합니다.

요금 모델은 흉내낼 수 없습니다 — S3 Glacier 복원 시간 · Lambda 콜드 스타트 같은 비용·지연 모델 없음.

버전 차이 — LocalStack 은 빈번히 새 서비스를 추가, MiniStack 은 신생이라 버전이 자주 바뀝니다. 프로덕션 코드의 의존을 에뮬레이터 동작에 맞추지 말 것 — endpoint 만 의존.

CI 에서 띄울 때는 컨테이너 시작 후 _localstack/health 또는 _ministack/health 를 폴링해서 ready 가 됐는지 확인. 단순히 up -d 직후 호출하면 503.

하고픈 말

로컬 에뮬레이터는 클라우드 학습·개발의 비용을 거의 0 으로 만듭니다. mock 충실도는 LocalStack, 진짜 인프라 동작은 MiniStack — 둘을 함께 띄우는 모양이 가장 단단합니다. 다만 본 운용 검증은 실제 AWS 에서 한 번은 거쳐야 한다는 원칙은 변하지 않습니다.

Next

• supabase-self-hosted
• firebase-emulator

LocalStack · LocalStack GitHub · MiniStack · boto3 · @aws-sdk/client-s3 · awslocal 을 참고합니다.