Como Configurar o IronPDF for Java na AWS

Índice

• Quais são os Pré-requisitos?
• Por que você deve usar Docker em vez de Implantação Zip?
• Como você configura as dependências do Maven?
• Como você escreve o manipulador Lambda?
• Como você configura o Modelo SAM?
• Como você constrói o Dockerfile?
• Como você constrói e implanta a Função Lambda?
• Quais são os próximos passos?

Quais são os Pré-requisitos? {#pré-requisitos}

Antes de começar, confirme que as seguintes ferramentas estão instaladas na máquina de desenvolvimento. Cada ferramenta desempenha um papel específico no pipeline de construção e implantação.

• IntelliJ IDEA — o IDE usado neste guia. Baixe em jetbrains.com/idea.
• AWS Toolkit for JetBrains — fornece o assistente de projeto SAM e as configurações de execução Lambda dentro do IntelliJ. As instruções de configuração estão na página de documentação do AWS Toolkit for JetBrains.
• AWS SAM CLI — a ferramenta de linha de comandos que constrói imagens Docker e implanta funções Lambda. Instale-a seguindo o guia de instalação do SAM CLI.
• Docker Desktop — necessário porque a função Lambda é empacotada como uma imagem de contêiner, não um arquivo Zip. Baixe Docker Community Edition.

Para testes de invocação local antes da implantação na AWS, também instale:

• Java 8 JDK — disponível na página de downloads do Oracle JDK 8.
• Apache Maven — siga o guia de instalação do Maven.

Uma vez que todas as ferramentas estejam no lugar, abra o IntelliJ IDEA e crie um novo projeto via File → New → Project. No assistente de projetos, selecione o modelo AWS Lambda e escolha as seguintes opções:

• Tipo de Pacote: Image
• Tempo de Execução: java8 ou java11
• Modelo SAM: Maven

Por que você deve usar Docker em vez de Implantação Zip? {#por que-docker}

AWS Lambda suporta dois tipos de pacote de implantação: arquivos Zip e imagens de contêiner. A implantação Zip funciona bem para funções Java leves porque o ambiente de runtime é totalmente gerenciado pela AWS. No entanto, IronPDF envia um binário nativo — um motor de renderização de PDF baseado em Chrome — que deve ser extraído e executado em tempo de execução. O ambiente de execução Lambda para implantações Zip restringe gravações no sistema de arquivos a /tmp, e as limitações da camada do pacote Zip impedem a extração de grandes binários nativos.

A implantação de imagem de contêiner remove essas restrições. Quando você define sua própria imagem Docker, você controla o sistema operacional base, os pacotes do sistema instalados e o layout do diretório. O motor de renderização do IronPDF pode ser extraído para /tmp na inicialização, as bibliotecas do sistema necessárias podem ser pré-instaladas na imagem, e o limite de tamanho do container (10 GB) é suficientemente grande para acomodar o motor completo.

A consequência prática é simples: defina PackageType: Image em template.yaml e construa usando uma imagem base compatível com Docker. O SAM CLI cuida do resto.

Como você configura as dependências do Maven? {#maven-dependencies}

O arquivo pom.xml precisa de três categorias de dependências adicionais além do SDK padrão do Lambda: a biblioteca Java do IronPDF, o motor de renderização IronPDF Linux x64, e o transporte gRPC usado internamente pelo motor do IronPDF.

Abra pom.xml e adicione as seguintes dependências dentro de <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>

O artefato ironpdf-engine-linux-x64 empacota o motor de renderização pré-compilado baseado em Chromium para Linux 64 bits. É isso que permite que o IronPDF renderize HTML para PDF dentro do contêiner Lambda. Sem ele, as chamadas de renderização falharão com um erro de binário ausente. As dependências gRPC (grpc-okhttp, grpc-netty-shaded, perfmark-api) são necessárias porque IronPDF se comunica com seu motor de renderização por um canal local gRPC. A dependência slf4j-simple fornece uma implementação mínima de logging para que os logs internos do IronPDF sejam visíveis no CloudWatch.

Sempre alinhe os números de versão de ironpdf e ironpdf-engine-linux-x64 — misturar versões causará falha de inicialização. Confira IronPDF for Java no Maven Central para a string de versão mais recente.

Como você escreve o manipulador Lambda? {#lambda-handler}

A classe manipuladora Lambda recebe um(a) APIGatewayProxyRequestEvent, gera um PDF, e retorna um(a) APIGatewayProxyResponseEvent. Duas chamadas de configuração do IronPDF devem aparecer antes da primeira operação de renderização: definir o diretório de trabalho para /tmp e, opcionalmente, habilitar o logging de depuração.

Substitua o conteúdo de App.java pelo seguinte:

//: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() + "\"}");
        }
    }
}

A chamada para Settings.setIronPdfEngineWorkingDirectory(Paths.get("/tmp/")) é obrigatória. O ambiente de execução do AWS Lambda monta o código da função em um diretório somente leitura. O mecanismo IronPDF deve extrair arquivos de suporte e criar sockets na inicialização - atividades que requerem acesso de gravação. O diretório /tmp é o único local que o Lambda permite para gravações de arquivo, então IronPDF deve ser direcionado para lá antes do início de qualquer renderização. Se esta configuração for omitida, o mecanismo falhará ao iniciar e cada chamada de renderização lançará uma exceção.

A chamada pdf.saveAs("/tmp/output.pdf") armazena o arquivo renderizado no sistema de arquivos efêmero /tmp. Se a função Lambda precisar retornar o PDF como uma resposta binária ou carregá-lo no S3, recupere os bytes com pdf.getBinaryData() em vez de escrever no disco. Para cargas de trabalho em grande escala, o envio para o Amazon S3 e o retorno de uma URL pré-assinada é o padrão recomendado.

Como você configura o Modelo SAM? {#sam-template}

O arquivo template.yaml controla a alocação de recursos da função Lambda. Três configurações afetam diretamente se o IronPDF é executado com sucesso: Timeout, MemorySize e EphemeralStorage.Size.

Atualize a seção Globals de template.yaml da seguinte forma:

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

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

Timeout é definido para 400 segundos. Em uma inicialização a frio, IronPDF deve extrair o motor de renderização para /tmp e iniciar um processo local do Chromium. Essa extração pode levar de 30 a 60 segundos na primeira invocação. Um tempo limite inferior a 330 segundos fará com que as invocações a frio falhem com um erro de tempo limite de tarefa. Invocações rápidas são muito mais rápidas — tipicamente abaixo de 5 segundos para conversões simples de HTML para PDF.

MemorySize é definido para 2048 MB. O renderizador Chromium exige muita memória. A memória mínima viável do AWS Lambda para o IronPDF é de 1024 MB, mas 2048 MB reduzem o risco de falhas por falta de memória para páginas complexas e produzem tempos de renderização perceptivelmente mais rápidos, porque o Lambda também escala a alocação de CPU proporcionalmente com a memória.

EphemeralStorage.Size é definido para 1024 MB. A alocação padrão do Lambda /tmp é 512 MB. IronPDF grava os binários do motor de renderização, cache de fontes, e arquivos temporários de renderização para /tmp. Esses ativos podem exceder 512 MB em um início a frio, o que faz com que a extração do mecanismo falhe. Definir o armazenamento efêmero para pelo menos 1024 MB previne esse modo de falha.

Como você constrói o Dockerfile? {#dockerfile}

O Dockerfile é o coração desta implantação. Ele executa uma construção de múltiplos estágios: o primeiro estágio compila o projeto Java usando uma imagem de construção Maven; o segundo estágio cria a imagem de runtime final do Lambda com base no Amazon Linux 2, instala os pacotes do sistema que o mecanismo Chromium do IronPDF requer e copia os artefatos compilados.

Abra o Dockerfile do projeto e substitua seu conteúdo pelo seguinte:

//: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"]

As imagens base para ambos os estágios usam o tag java8.al2 em vez de java8 simples. O sufixo .al2 indica Amazon Linux 2, que é necessário para IronPDF. A imagem java8 mais antiga roda no Amazon Linux 1 original, que usa repositórios yum que não recebem mais atualizações e carece de vários pacotes dos quais o IronPDF depende. Sempre use imagens .al2 ao implantar o IronPDF no Java 8.

O bloco yum install instala as bibliotecas relacionadas ao X11, GTK3, Pango, e fonte que o Chromium precisa para renderizar páginas. Omitir qualquer um destes pacotes pode produzir saída de PDF incompleta ou fazer com que o mecanismo de renderização falhe com um erro de biblioteca compartilhada ausente. O pacote libgdiplus é necessário para compatibilidade com GDI+, que é usado por algumas operações de desenho do IronPDF.

Atualize a instrução CMD para corresponder ao seu nome de pacote e classe reais, se eles diferirem de helloworld.App.

Como você constrói e implanta a Função Lambda? {#build-deploy}

Com o Dockerfile, template.yaml, pom.xml, e App.java todos configurados, execute os seguintes dois comandos do SAM CLI a partir do diretório raiz do projeto.

Passo 1 — Construa a imagem do contêiner:

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

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

A flag -u instrui o SAM a usar o Docker (o modo "use container"). O SAM executa o Dockerfile de múltiplos estágios, que compila o projeto Maven e produz a imagem final do Lambda. Espere que esta etapa demore vários minutos na primeira execução enquanto o Docker baixa as imagens base.

Passo 2 — Implantar no AWS:

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

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

A flag --guided lança um prompt interativo que pergunta pelo nome da pilha, região AWS, bucket S3 para artefatos, e se deseja confirmar conjuntos de alterações antes da implantação. Responda aos prompts, e o SAM enviará a imagem do container para o Amazon ECR e criará a função Lambda, API Gateway, e função IAM definir em template.yaml.

Após a conclusão da implantação, o SAM CLI exibe o URL do endpoint da API. Abra o Console do AWS Lambda para ver a função implantada, executar invocações de teste e inspecionar logs do CloudWatch para saída de depuração do IronPDF.

Na primeira invocação (inicialização a frio), espere um tempo de resposta de 60–120 segundos enquanto o ambiente de execução Lambda inicia e o IronPDF extrai seu motor de renderização para /tmp. As invocações subsequentes na mesma instância aquecida retornarão em poucos segundos. Se a latência do início a frio for uma preocupação para cargas de trabalho de produção, considere usar Concorrência Provisionada Lambda para manter instâncias aquecidas.

Você também pode testar a função localmente antes de implantar executando sam local invoke com uma carga de evento de teste, desde que o Docker esteja rodando na máquina de desenvolvimento.

Quais são os próximos passos? {#próximos-passos}

A função Lambda agora está implantada e gerando PDFs. Os seguintes guias cobrem os próximos passos mais comuns após uma implantação bem-sucedida do IronPDF:

• IronPDF for Java — Introdução — visão geral da API completa do IronPDF Java, incluindo HTML para PDF, URL para PDF e estampagem de PDF.
• Como Gerar PDFs a partir de HTML em Java — renderizando strings HTML, arquivos e modelos em PDF.
• Como Aplicar Cabeçalhos e Rodapés a PDFs em Java — adicionando números de páginas, logotipos e cabeçalhos de texto a PDFs gerados por Lambda.
• Como Adicionar Marcas d'Água a PDFs em Java — estampando a saída de PDF com marcas d'água de texto ou imagem antes de retornar ao chamador.
• Licenciamento do IronPDF — opções de licença para implantações Lambda de produção, incluindo licenciamento por contagem de implantações.

Inicie um teste gratuito do IronPDF for Java para gerar e editar PDFs na sua função Lambda sem restrições durante a avaliação. Quando estiver pronto para implantar em produção, veja as opções de licenciamento do IronPDF para encontrar o plano que se adapta à sua carga de trabalho sem servidor.