본문으로 건너뛰기

AWS Lambda에 Mastra 배포

Docker 컨테이너와AWS Lambda Web Adapter. 이 접근 방식은 자동 조정 기능을 갖춘 컨테이너화된 Lambda 함수로 Mastra 서버를 실행합니다.

정보

이 가이드에서는Mastra server. If you're using a server adapter또는웹 프레임워크, 해당 프레임워크에 대해 일반적인 방식으로 배포합니다.

시작하기 전에
시작하기 전에에 대한 직접 링크

다음이 필요합니다.

경고

AWS Lambda에서 파일 시스템은 임시적이므로 호출 사이에 로컬 데이터베이스 파일이 손실됩니다. 당신이 사용하는 경우LibSQLStore 로컬 파일과 함께 사용하는 경우, 원격 LibSQL 호환 데이터베이스(예: Turso) instead.

Dockerfile 만들기
Dockerfile 만들기에 대한 직접 링크

만들기Dockerfile in your project root:

Dockerfile
FROM node:22-alpine

WORKDIR /app

# Install dependencies
COPY package*.json ./
RUN npm ci

# Copy source and build Mastra
COPY src ./src
RUN npx mastra build

# Alpine compatibility for some native deps
RUN apk add --no-cache gcompat

# Add the Lambda Web Adapter
COPY --from=public.ecr.aws/awsguru/aws-lambda-adapter:0.9.1 /lambda-adapter /opt/extensions/lambda-adapter

# Run as non-root
RUN addgroup -g 1001 -S nodejs && \
  adduser -S mastra -u 1001 && \
  chown -R mastra:nodejs /app

USER mastra

# Adapter / app configuration
ENV PORT=8080
ENV NODE_ENV=production
ENV AWS_LWA_READINESS_CHECK_PATH="/api"

# Start the Mastra server
CMD ["node", ".mastra/output/index.mjs"]

:::참고 이 Dockerfile은 npm을 사용합니다. pnpm, Yarn 또는 다른 패키지 관리자를 사용하는 경우 그에 따라 명령을 조정하세요(예:npm ci won't work with pnpm lockfiles). :::

Docker 이미지 빌드 및 푸시
Docker 이미지 빌드 및 푸시에 대한 직접 링크

  1. 배포를 위한 환경 변수를 설정합니다. 모든 AWS 서비스(ECR, Lambda)에 동일한 지역을 사용하여 리소스가 여러 지역에 걸쳐 표시되지 않는 문제를 방지합니다.

    export PROJECT_NAME="your-mastra-app"
    export AWS_REGION="us-east-1"
    export AWS_ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)

  2. Docker 이미지를 빌드하세요. 이미지가 Lambda의 컨테이너 런타임과 호환되는지 확인하려면 BuildKit을 비활성화합니다.

    export DOCKER_BUILDKIT=0
    docker build --platform linux/arm64 -t "$PROJECT_NAME" .

    :::참고 BuildKit의 기본 이미지 형식은 Lambda와의 호환성 문제를 일으킬 수 있습니다. 환경DOCKER_BUILDKIT=0 는 Lambda가 안정적으로 허용하는 형식의 이미지를 생성하는 클래식 빌더를 사용합니다. :::

  3. Docker 이미지를 저장할 Amazon ECR 리포지토리를 생성합니다.

    aws ecr create-repository --repository-name "$PROJECT_NAME" --region "$AWS_REGION"

  4. Amazon ECR에 로그인합니다.

    aws ecr get-login-password --region "$AWS_REGION" | \
      docker login --username AWS --password-stdin \
      "$AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com"

  5. 이미지에 태그를 지정하고 ECR에 푸시합니다.

    docker tag "$PROJECT_NAME":latest \
      "$AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/$PROJECT_NAME":latest

    docker push \
      "$AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/$PROJECT_NAME":latest

Lambda 함수 생성
Lambda 함수 생성에 대한 직접 링크

  1. 다음으로 이동하세요.AWS Lambda Console and click Create function. ECR 리포지토리를 생성한 리전과 동일한 리전이 선택되어 있는지 확인하세요.

  2. 선택하다Container image and configure the function:

    • 기능 이름: 이름을 입력하세요(예:mastra-app)
    • 컨테이너 이미지 URI: 클릭Browse images, select your ECR repository, and choose the latest tag
    • 건축학: 선택하다arm64

    딸깍 하는 소리Create function to create the Lambda function.

  3. Memory 및 시간 초과를 구성합니다. 이동Configuration > General configuration and click Edit:

    • Memory: 512MB(애플리케이션 요구 사항에 따라 조정)
    • 시간 초과: 1분 이상(기본 3초는 대부분의 Mastra 애플리케이션에서 너무 낮음)

    딸깍 하는 소리Save.

  4. 환경 변수를 추가합니다. 이동Configuration > Environment variables and click Edit. Add the variables your Mastra application needs:

    • OPENAI_API_KEY: OpenAI API 키(OpenAI를 사용하는 경우)
    • ANTHROPIC_API_KEY: 귀하의 Anthropic API 키(Anthropic을 사용하는 경우)
    • 필요에 따라 기타 공급자별 API 키(예:TURSO_DATABASE_URL and TURSO_AUTH_TOKEN if using LibSQL with Turso)

    딸깍 하는 소리Save.

  5. 외부 액세스를 위해 함수 URL을 활성화합니다. 이동Configuration > Function URL and click Create function URL:

    • 인증 유형: 선택하다NONE for public access
    • 아래에Additional settings, check Configure cross-origin resource sharing (CORS), then configure:
      • 원산지 허용: *
      • 헤더 허용: content-type (x-amzn-request-context 는 CloudFront/API Gateway 같은 서비스와 함께 사용할 때도 필요합니다.)
      • 메소드 허용: *

    딸깍 하는 소리Save.

배포 확인
배포 확인에 대한 직접 링크

  1. 복사Function URL from the Lambda console and visit <your-function-url>/api/agents 를 브라우저에서 여세요. Agent의 JSON 목록이 표시되어야 합니다.

  2. 이제 HTTP를 통해 Mastra 엔드포인트를 호출할 수 있습니다.

    경고

    프로덕션 배포의 경우 다음을 설정합니다.authentication 엔드포인트를 공개하기 전에 CORS 출처를 신뢰할 수 있는 도메인으로 제한하고, 다른 AWS 서비스에 안전하게 액세스할 수 있도록 AWS IAM 역할을 사용하며, 민감한 환경 변수는 AWS Secrets Manager 또는 Parameter Store에 저장하세요.

다음 단계
다음 단계에 대한 직접 링크

이 가이드는 Mastra를 AWS Lambda에 배포하기 위한 빠른 시작을 제공합니다. 프로덕션 워크로드의 경우 활성화를 고려하세요.CloudWatch monitoring for your Lambda function, setting up AWS X-Ray for distributed tracing, and configuring provisioned concurrency for consistent performance.

On this page