LocalStack 과 MiniStack — 로컬에서 AWS 흉내내기
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 을 참고합니다.