목차

• 필수 사전 준비사항
• 왜 Zip 배포 대신 Docker를 사용해야 합니까?
• Maven 의존성을 어떻게 구성합니까?
• Lambda 핸들러를 어떻게 작성합니까?
• SAM 템플릿을 어떻게 구성합니까?
• Dockerfile을 어떻게 작성합니까?
• Lambda 함수를 어떻게 작성하고 배포합니까?
• 다음 단계는 무엇입니까?

필수 사전 준비사항 {#prerequisites}

시작하기 전에, 다음 도구들이 개발 머신에 설치되어 있는지 확인하십시오. 각 도구는 빌드 및 배포 파이프라인에서 특정 역할을 담당합니다.

• IntelliJ IDEA — 이 가이드에서 사용되는 IDE입니다. jetbrains.com/idea에서 다운로드하십시오.
• AWS Toolkit for JetBrains — IntelliJ 내에서 SAM 프로젝트 마법사 및 Lambda 실행 구성을 제공합니다. AWS Toolkit for JetBrains 문서 페이지에서 설정 지침 확인
• AWS SAM CLI — Docker 이미지를 빌드하고 Lambda 함수를 배포하는 커맨드 라인 도구입니다. SAM CLI 설치 가이드를 따라 설치하십시오.
• Docker Desktop — Lambda 함수가 Zip 아카이브가 아닌 컨테이너 이미지로 패키지되므로 필요합니다. Docker Community Edition을 다운로드하십시오.

AWS에 배포하기 전에 로컬 호출 테스트를 위해서도 다음을 설치하십시오:

• Java 8 JDK — Oracle JDK 8 다운로드 페이지에서 사용할 수 있습니다.
• Apache Maven — Maven 설치 가이드를 따르십시오.

모든 도구가 준비된 후, IntelliJ IDEA를 열고 파일 → 새로 만들기 → 프로젝트를 통해 새 프로젝트를 생성합니다. 프로젝트 마법사에서 AWS Lambda 템플릿을 선택하고 다음 옵션을 선택하십시오:

• 패키지 유형: Image
• 런타임: java8 또는 java11
• SAM 템플릿: Maven

왜 Zip 배포 대신 Docker를 사용해야 합니까? {#why-docker}

AWS Lambda는 두 가지 배포 패키지 유형을 지원합니다: Zip 아카이브와 컨테이너 이미지. Zip 배포는 경량 Java 함수에 적합합니다. 왜냐하면 실행 환경이 AWS에 의해 완전히 관리되기 때문입니다. 그러나 IronPDF는 런타임 시 추출하여 실행해야 하는 네이티브 바이너리(Chrome 기반 PDF 렌더링 엔진)를 포함하고 있습니다. ZIP 배포용 Lambda 실행 환경은 파일 시스템 쓰기 작업을 /tmp로 제한하며, ZIP 패키지 계층의 제한으로 인해 대용량 네이티브 바이너리를 추출할 수 없습니다.

컨테이너 이미지 배포는 이러한 제약을 제거합니다. Docker 이미지를 정의하면 기본 운영 체제, 설치된 시스템 패키지, 디렉토리 레이아웃을 제어할 수 있습니다. IronPDF의 렌더링 엔진은 시작 시 /tmp로 추출할 수 있으며, 필요한 시스템 라이브러리는 이미지에 미리 설치할 수 있고, 컨테이너 크기 제한(10GB)은 전체 엔진을 수용하기에 충분히 큽니다.

실질적인 결과는 간단합니다. PackageType: Image을 template.yaml에 설정하고 Docker를 지원하는 기본 이미지를 사용하여 빌드하십시오. SAM CLI가 나머지를 처리합니다.

Maven 의존성을 어떻게 구성합니까? {#Maven-dependencies}

pom.xml 파일에는 표준 Lambda SDK 외에도 세 가지 범주의 추가 종속성이 필요합니다. IronPDF Java 라이브러리, IronPDF Linux x64 렌더링 엔진, 그리고 IronPDF 엔진에서 내부적으로 사용하는 gRPC 전송 프로토콜입니다.

pom.xml를 열고 <dependencies> 안에 다음 종속성을 추가하십시오:

//:path=pom.xml
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf</artifactId>
    <version>2024.9.1</version>
</dependency>
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf-engine-linux-x64</artifactId>
    <version>2024.9.1</version>
</dependency>
<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-simple</artifactId>
    <version>2.0.3</version>
</dependency>
<dependency>
    <groupId>io.perfmark</groupId>
    <artifactId>perfmark-api</artifactId>
    <version>0.26.0</version>
</dependency>
<dependency>
    <groupId>io.grpc</groupId>
    <artifactId>grpc-okhttp</artifactId>
    <version>1.50.2</version>
</dependency>
<dependency>
    <groupId>io.grpc</groupId>
    <artifactId>grpc-netty-shaded</artifactId>
    <version>1.50.2</version>
</dependency>

//:path=pom.xml
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf</artifactId>
    <version>2024.9.1</version>
</dependency>
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf-engine-linux-x64</artifactId>
    <version>2024.9.1</version>
</dependency>
<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-simple</artifactId>
    <version>2.0.3</version>
</dependency>
<dependency>
    <groupId>io.perfmark</groupId>
    <artifactId>perfmark-api</artifactId>
    <version>0.26.0</version>
</dependency>
<dependency>
    <groupId>io.grpc</groupId>
    <artifactId>grpc-okhttp</artifactId>
    <version>1.50.2</version>
</dependency>
<dependency>
    <groupId>io.grpc</groupId>
    <artifactId>grpc-netty-shaded</artifactId>
    <version>1.50.2</version>
</dependency>

ironpdf-engine-linux-x64 아티팩트는 64비트 Linux용 사전 컴파일된 Chromium 기반 렌더링 엔진을 포함합니다. 이것이 IronPDF가 Lambda 컨테이너 내에서 HTML을 PDF로 렌더링할 수 있도록 합니다. 이것이 없다면, 렌더링 호출들은 누락된 바이너리 에러로 실패할 것입니다. IronPDF가 로컬 gRPC 채널을 통해 렌더링 엔진과 통신하기 때문에 gRPC 종속성(grpc-okhttp, grpc-netty-shaded, perfmark-api)이 필요합니다. slf4j-simple 종속성은 최소한의 로깅 구현을 제공하여 CloudWatch에서 IronPDF의 내부 로그를 확인할 수 있도록 합니다.

ironpdf 및 ironpdf-engine-linux-x64 버전 번호는 항상 일치시켜야 합니다. 버전이 섞이면 시작 오류가 발생합니다. Maven Central에서 Java용 IronPDF에서 최신 버전 문자열 확인

Lambda 핸들러를 어떻게 작성합니까? {#lambda-handler}

Lambda 핸들러 클래스는 APIGatewayProxyRequestEvent을 수신하여 PDF를 생성하고, APIGatewayProxyResponseEvent을 반환합니다. 첫 번째 렌더링 작업 전에 두 가지 IronPDF 구성 호출이 포함되어야 합니다: 작업 디렉터리를 /tmp로 설정하고, 선택적으로 디버그 로깅을 활성화하는 것입니다.

App.java의 내용을 다음으로 대체하십시오:

//:path=App.java
import com.amazonaws.services.lambda.runtime.Context;
import com.amazonaws.services.lambda.runtime.events.APIGatewayProxyRequestEvent;
import com.amazonaws.services.lambda.runtime.events.APIGatewayProxyResponseEvent;
import com.ironsoftware.ironpdf.PdfDocument;
import com.ironsoftware.ironpdf.Settings;

import java.nio.file.Paths;
import java.util.HashMap;
import java.util.Map;

public class App {
    public APIGatewayProxyResponseEvent handleRequest(
            final APIGatewayProxyRequestEvent input,
            final Context context) {

        APIGatewayProxyResponseEvent response = new APIGatewayProxyResponseEvent();

        // IronPDF must write its engine binaries and temporary files to /tmp.
        // This is the only writable path available in the Lambda execution environment.
        Settings.setIronPdfEngineWorkingDirectory(Paths.get("/tmp/"));

        // Enable debug logging to CloudWatch during initial testing.
        Settings.setDebug(true);

        try {
            context.getLogger().log("Starting PDF render");

            // Render a PDF from a live URL. Replace with your own HTML or URL as needed.
            PdfDocument pdf = PdfDocument.renderUrlAsPdf("https://www.google.com");

            context.getLogger().log("PDF render complete");

            // Save the rendered PDF to /tmp. Files in /tmp persist for the lifetime
            // of the Lambda execution environment (warm instance).
            pdf.saveAs("/tmp/output.pdf");

            Map<String, String> headers = new HashMap<>();
            headers.put("Content-Type", "application/json");

            return response
                    .withStatusCode(200)
                    .withHeaders(headers)
                    .withBody("PDF generated successfully.");

        } catch (Exception e) {
            context.getLogger().log("PDF render failed: " + e.getMessage());
            return response
                    .withStatusCode(500)
                    .withBody("{\"error\": \"" + e.getMessage() + "\"}");
        }
    }
}

//:path=App.java
import com.amazonaws.services.lambda.runtime.Context;
import com.amazonaws.services.lambda.runtime.events.APIGatewayProxyRequestEvent;
import com.amazonaws.services.lambda.runtime.events.APIGatewayProxyResponseEvent;
import com.ironsoftware.ironpdf.PdfDocument;
import com.ironsoftware.ironpdf.Settings;

import java.nio.file.Paths;
import java.util.HashMap;
import java.util.Map;

public class App {
    public APIGatewayProxyResponseEvent handleRequest(
            final APIGatewayProxyRequestEvent input,
            final Context context) {

        APIGatewayProxyResponseEvent response = new APIGatewayProxyResponseEvent();

        // IronPDF must write its engine binaries and temporary files to /tmp.
        // This is the only writable path available in the Lambda execution environment.
        Settings.setIronPdfEngineWorkingDirectory(Paths.get("/tmp/"));

        // Enable debug logging to CloudWatch during initial testing.
        Settings.setDebug(true);

        try {
            context.getLogger().log("Starting PDF render");

            // Render a PDF from a live URL. Replace with your own HTML or URL as needed.
            PdfDocument pdf = PdfDocument.renderUrlAsPdf("https://www.google.com");

            context.getLogger().log("PDF render complete");

            // Save the rendered PDF to /tmp. Files in /tmp persist for the lifetime
            // of the Lambda execution environment (warm instance).
            pdf.saveAs("/tmp/output.pdf");

            Map<String, String> headers = new HashMap<>();
            headers.put("Content-Type", "application/json");

            return response
                    .withStatusCode(200)
                    .withHeaders(headers)
                    .withBody("PDF generated successfully.");

        } catch (Exception e) {
            context.getLogger().log("PDF render failed: " + e.getMessage());
            return response
                    .withStatusCode(500)
                    .withBody("{\"error\": \"" + e.getMessage() + "\"}");
        }
    }
}

Settings.setIronPdfEngineWorkingDirectory(Paths.get("/tmp/")) 호출은 필수입니다. AWS Lambda의 실행 환경은 함수 코드를 읽기 전용 디렉토리에 마운트합니다. IronPDF 엔진은 지원 파일을 추출하고 시작 시 소켓을 생성해야 합니다 — 이는 쓰기 권한이 필요합니다. /tmp 디렉터리는 Lambda가 파일 쓰기를 허용하는 유일한 위치이므로, 렌더링을 시작하기 전에 IronPDF를 해당 위치로 지정해야 합니다. 이 설정을 누락하면 엔진이 시작되지 못하고 모든 렌더링 호출은 예외를 던질 것입니다.

pdf.saveAs("/tmp/output.pdf") 호출은 렌더링된 파일을 임시 /tmp 파일 시스템에 저장합니다. Lambda 함수가 PDF를 바이너리 응답으로 반환하거나 S3에 업로드해야 하는 경우, 디스크에 기록하는 대신 pdf.getBinaryData()를 사용하여 바이트를 가져오십시오. 대규모 작업 부하의 경우, Amazon S3에 업로드하고 사전 서명된 URL을 반환하는 것이 권장 패턴입니다.

SAM 템플릿을 어떻게 구성합니까? {#sam-template}

template.yaml 파일은 Lambda 함수의 리소스 할당을 제어합니다. IronPDF가 성공적으로 실행되는지 여부에 직접적인 영향을 미치는 세 가지 설정은 Timeout, MemorySize 및 EphemeralStorage.Size입니다.

Globals 섹션을 다음과 같이 template.yaml에 업데이트하십시오:

//:path=template.yaml
Globals:
  Function:
    Timeout: 400
    MemorySize: 2048
    EphemeralStorage:
      Size: 1024

//:path=template.yaml
Globals:
  Function:
    Timeout: 400
    MemorySize: 2048
    EphemeralStorage:
      Size: 1024

시간 제한은 400초로 설정됩니다. 콜드 스타트 시, IronPDF는 렌더링 엔진을 /tmp로 추출하고 로컬 Chromium 프로세스를 실행해야 합니다. 초기 호출시 이 추출은 30–60초가 소요될 수 있습니다. 330초보다 짧은 시간 제한은 콜드 스타트 호출을 작업 시간 초과 오류로 실패하게 합니다. 따뜻한 호출은 훨씬 빠릅니다 — 간단한 HTML-to-PDF 변환의 경우 일반적으로 5초 이내입니다.

메모리 크기는 2048 MB로 설정됩니다. Chromium 렌더러는 메모리 집약적입니다. AWS Lambda의 IronPDF에 대한 최소 구동 가능한 메모리는 1024MB이지만, 2048MB는 복잡한 페이지에서 메모리 부족 오류의 위험을 줄이고, Lambda가 메모리와 비례하여 CPU 할당을 조정하기 때문에 눈에 띄게 빠른 렌더링 시간을 제공합니다.

일시적 저장소 크기는 1024 MB로 설정됩니다. Lambda의 기본 /tmp 할당량은 512MB입니다. IronPDF는 렌더링 엔진 바이너리, 글꼴 캐시 및 임시 렌더링 파일을 /tmp에 기록합니다. 이 자산은 콜드 스타트 시 512 MB를 초과할 수 있으며, 이는 엔진 추출을 실패하게 만듭니다. 일시적 저장소를 최소한 1024 MB로 설정하면 이러한 실패 모드를 방지합니다.

Dockerfile을 어떻게 작성합니까? {#dockerfile}

Dockerfile은 이 배포의 핵심입니다. 멀티 스테이지 빌드를 수행합니다: 첫 번째 단계는 Maven 빌드 이미지를 사용하여 Java 프로젝트를 컴파일합니다; 두 번째 단계는 Amazon Linux 2를 기반으로 최종 Lambda 런타임 이미지를 생성하고, IronPDF의 Chromium 엔진에 필요한 시스템 패키지를 설치하고, 컴파일된 아티팩트를 복사합니다.

프로젝트의 Dockerfile 파일을 열고 그 내용을 다음 내용으로 대체하십시오:

//:path=Dockerfile
# Stage 1: Build the Maven project
FROM public.ecr.aws/sam/build-java8.al2:latest AS build-image
WORKDIR /task
COPY src/ src/
COPY pom.xml ./
RUN mvn -q clean install
RUN mvn dependency:copy-dependencies -DincludeScope=compile

# Stage 2: Create the Lambda runtime image
FROM public.ecr.aws/lambda/java:8.al2

# Update the package index and install system libraries required by Chromium.
# These packages provide font rendering, graphics, audio, GTK3, and input
# method support — all needed by the headless browser inside IronPDF.
RUN yum update -y && \
    yum install -y \
        pango.x86_64 \
        libXcomposite.x86_64 \
        libXcursor.x86_64 \
        libXdamage.x86_64 \
        libXext.x86_64 \
        libXi.x86_64 \
        libXtst.x86_64 \
        cups-libs.x86_64 \
        libXScrnSaver.x86_64 \
        libXrandr.x86_64 \
        GConf2.x86_64 \
        alsa-lib.x86_64 \
        atk.x86_64 \
        gtk3.x86_64 \
        ipa-gothic-fonts \
        xorg-x11-fonts-100dpi \
        xorg-x11-fonts-75dpi \
        xorg-x11-utils \
        xorg-x11-fonts-cyrillic \
        xorg-x11-fonts-Type1 \
        xorg-x11-fonts-misc \
        glibc-devel.x86_64 \
        at-spi2-atk.x86_64 \
        mesa-libgbm.x86_64 \
        libxkbcommon \
        amazon-linux-extras && \
    amazon-linux-extras install epel -y && \
    yum install -y libgdiplus

# Ensure /tmp is writable by the Lambda execution user.
RUN chmod 777 /tmp/

# Copy the compiled classes and dependencies from the build stage.
COPY --from=build-image /task/target/classes /var/task/
COPY --from=build-image /task/target/dependency /var/task/lib

# Entry point: package.ClassName::methodName
CMD ["helloworld.App::handleRequest"]

두 단계의 기본 이미지는 일반 java8 태그 대신 java8.al2 태그를 사용합니다. .al2 접미사는 IronPDF에 필요한 Amazon Linux 2를 나타냅니다. 이전 java8 이미지는 더 이상 업데이트되지 않는 yum 저장소를 사용하고 IronPDF가 의존하는 여러 패키지가 누락된 기존 Amazon Linux 1에서 실행됩니다. Java 8에서 IronPDF를 배포할 때는 항상 .al2 이미지를 사용하십시오.

yum install 블록은 Chromium이 페이지를 렌더링하는 데 필요한 X11, GTK3, Pango 및 글꼴 관련 라이브러리를 설치합니다. 이러한 패키지를 생략하면 PDF 출력이 불완전하게 되거나 렌더링 엔진이 누락된 공유 라이브러리 오류로 충돌할 수 있습니다. 일부 IronPDF 그리기 작업에서 사용되는 GDI+ 호환성을 위해 libgdiplus 패키지가 필요합니다.

CMD 지시문은 helloworld.App와 다른 경우, 실제 패키지 및 클래스 이름에 맞게 수정하십시오.

Lambda 함수를 어떻게 작성하고 배포합니까? {#build-deploy}

Dockerfile, template.yaml, pom.xml 및 App.java의 구성이 모두 완료되면, 프로젝트 루트 디렉터리에서 다음 두 가지 SAM CLI 명령을 실행하십시오.

1단계 — 컨테이너 이미지 빌드:

//:path=build.sh
sam build -u

//:path=build.sh
sam build -u

-u 플래그는 SAM이 Docker를 사용하도록 지시합니다("컨테이너 사용" 모드). SAM은 Maven 프로젝트를 컴파일하고 최종 Lambda 이미지를 생성하는 다단계 Dockerfile을 실행합니다. 이 단계에서 Docker가 기본 이미지를 가져오는 동안, 처음 실행 시 몇 분이 걸릴 수 있습니다.

2단계 — AWS에 배포:

//:path=deploy.sh
sam deploy --guided

//:path=deploy.sh
sam deploy --guided

--guided 플래그를 사용하면 스택 이름, AWS 리전, 아티팩트용 S3 버킷, 배포 전 변경 세트 확인 여부를 묻는 대화형 프롬프트가 실행됩니다. 지시 사항에 따라 답변하면, SAM이 컨테이너 이미지를 Amazon ECR에 푸시하고 template.yaml에 정의된 Lambda 함수, API Gateway 및 IAM 역할을 생성합니다.

배포 완료 후, SAM CLI는 API 엔드포인트 URL을 출력합니다. AWS Lambda 콘솔을 열어 배포된 함수를 확인하고 테스트 호출을 실행하며 IronPDF 디버그 출력을 위한 CloudWatch 로그를 확인합니다.

첫 호출(콜드 스타트) 시에는 Lambda 실행 환경이 시작되고 IronPDF가 렌더링 엔진을 /tmp로 추출하는 과정에서 60~120초의 응답 시간이 소요될 수 있습니다. 동일한 웜 인스턴스에서 후속 호출은 몇 초 이내에 반환됩니다. 콜드 스타트 지연이 실생산 워크로드에서 문제가 된다면, 인스턴스를 계속 웜 상태로 유지하기 위해 Lambda Provisioned Concurrency를 사용하는 것을 고려하십시오.

개발 머신에서 Docker가 실행 중이라면, 테스트 이벤트 페이로드를 사용하여 sam local invoke을 실행함으로써 배포 전에 로컬에서 기능을 테스트할 수도 있습니다.

다음 단계는 무엇인가요? {#next-steps}

이제 Lambda 함수가 배포되어 PDF를 렌더링합니다. 다음 가이드는 IronPDF 배포 후의 가장 일반적인 다음 단계에 대해 설명합니다:

• IronPDF for Java — 시작하기 — HTML-to-PDF, URL-to-PDF 및 PDF 스탬핑을 포함한 전체 IronPDF Java API 개요.
• Java에서 HTML에서 PDF 생성하는 방법 — HTML 문자열, 파일 및 템플릿을 PDF로 렌더링.
• Java에서 PDF에 헤더와 푸터 적용하는 방법 — Lambda가 생성한 PDF에 페이지 번호, 로고 및 텍스트 헤더를 추가.
• Java에서 PDF에 워터마크 추가하는 방법 — 텍스트나 이미지 워터마크로 PDF 출력을 스탬핑하고 호출자에게 반환하기 전에.
• IronPDF 라이선싱 — 실행 단계 Lambda 배포를 위한 라이선스 옵션, 배포 수 라이선싱 포함.

IronPDF for Java 무료 체험판을 시작하여 평가 기간 동안 람다 함수에서 제한 없이 PDF를 생성하고 편집하십시오. 실행 환경에 배포할 준비가 되면 IronPDF 라이선스 옵션 보기를 클릭하여 서버리스 워크로드에 적합한 플랜을 찾으십시오.