LocalStack은 AWS 클라우드 서비스를 로컬 머신에서 에뮬레이션하는 오픈소스 도구입니다. 실제 AWS 계정 없이도 S3, SQS, Lambda, DynamoDB, API Gateway 등 주요 서비스를 로컬에서 실행하고 테스트할 수 있습니다. 개발자가 클라우드 환경과 동일한 코드를 로컬에서 바로 실행하고 검증할 수 있으므로, AWS 요금 걱정 없이 빠른 개발 피드백 사이클을 유지할 수 있습니다.
LocalStack은 Docker 컨테이너로 실행되며, 기본적으로 localhost:4566 포트에서 AWS API와 동일한 엔드포인트를 제공합니다. AWS SDK에서 엔드포인트 URL을 http://localhost:4566으로 지정하면, 실제 AWS 대신 LocalStack이 요청을 처리합니다.
개발자 코드
|
| AWS SDK 호출 (endpoint: http://localhost:4566)
v
LocalStack (Docker Container)
|
+--- S3 에뮬레이터
+--- SQS 에뮬레이터
+--- Lambda 에뮬레이터
+--- DynamoDB 에뮬레이터
+--- ...
실제 AWS 클라우드에는 요청이 가지 않음
Docker Compose를 사용하는 것이 가장 일반적입니다.
# docker-compose.yml
services:
localstack:
image: localstack/localstack
ports:
- "4566:4566"
environment:
- SERVICES=s3,sqs,lambda,dynamodb
- DEFAULT_REGION=ap-northeast-2
volumes:
- "/var/run/docker.sock:/var/run/docker.sock"
docker compose up -d
파일 업로드·다운로드 로직을 실제 S3 요금 없이 테스트합니다. 버킷 생성, 파일 업로드, 다운로드, 삭제, 이벤트 트리거 등 대부분의 S3 API가 지원됩니다.
# awslocal CLI (LocalStack용 AWS CLI 래퍼)
awslocal s3 mb s3://my-test-bucket
awslocal s3 cp ./file.txt s3://my-test-bucket/
awslocal s3 ls s3://my-test-bucket/
메시지 큐 송수신 로직을 로컬에서 테스트합니다. Consumer(소비자)와 Producer(생산자)를 각각 개발하고, 실제 SQS 없이 통합 테스트를 수행할 수 있습니다.
Lambda 함수를 로컬에서 실행하고 디버깅합니다. S3 이벤트나 SQS 메시지에 의해 Lambda가 트리거되는 흐름 전체를 LocalStack 안에서 재현할 수 있습니다.
DynamoDB 테이블을 로컬에서 생성하고 CRUD 로직을 테스트합니다. DynamoDB Local(AWS 공식 제공)의 대안으로 사용할 수 있으며, LocalStack을 통해 다른 서비스와 함께 통합 테스트하기 편리합니다.
Node.js AWS SDK v3 기준으로 엔드포인트를 LocalStack으로 지정하는 방법은 다음과 같습니다.
import { S3Client } from "@aws-sdk/client-s3";
const isLocal = process.env.NODE_ENV === "development";
const s3 = new S3Client({
region: "ap-northeast-2",
...(isLocal && {
endpoint: "http://localhost:4566",
forcePathStyle: true, // LocalStack S3 필수 설정
credentials: {
accessKeyId: "test", // LocalStack은 임의 값 허용
secretAccessKey: "test",
},
}),
});
환경 변수로 분기하면 동일한 코드가 로컬에서는 LocalStack을, 프로덕션에서는 실제 AWS를 사용하도록 구성할 수 있습니다.
통합 테스트 자동화: CI 환경(GitHub Actions, GitLab CI 등)에서 LocalStack을 컨테이너로 띄워 AWS 의존 로직의 통합 테스트를 자동화합니다. 실제 AWS 자격증명이나 비용 없이 파이프라인에서 AWS 연동 코드를 검증할 수 있습니다.
빠른 개발 피드백: Lambda 함수나 S3 이벤트 처리 로직을 개발할 때, 코드를 수정할 때마다 실제 AWS에 배포하지 않고 로컬에서 즉시 실행·확인합니다.
오프라인 개발: 인터넷이 없는 환경에서도 AWS 서비스를 사용하는 코드를 개발하고 테스트할 수 있습니다.
LocalStack의 무료 버전(Community)은 핵심 서비스를 지원하며, 유료 버전(Pro)은 더 많은 서비스와 고급 기능(영속성, CloudFormation 지원 등)을 제공합니다.