Comment configurer IronPDF for Java sur AWS

Table des matières

• Quels sont les prérequis ?
• Pourquoi devez-vous utiliser Docker au lieu du déploiement Zip ?
• Comment configurer les dépendances Maven ?
• Comment écrire le gestionnaire Lambda ?
• Comment configurer le modèle SAM ?
• Comment créer le fichier Dockerfile ?
• Comment créer et déployer la fonction Lambda ?
• Quelles sont les prochaines étapes ?

Quels sont les prérequis ?

Avant de commencer, confirmez que les outils suivants sont installés sur la machine de développement. Chaque outil joue un rôle spécifique dans le pipeline de construction et de déploiement.

• IntelliJ IDEA — l'IDE utilisé dans ce guide. Téléchargez-le depuis jetbrains.com/idea.
• AWS Toolkit for JetBrains — fournit l'assistant de projet SAM et les configurations de lancement Lambda dans IntelliJ. Les instructions de configuration se trouvent sur la page de documentation AWS Toolkit for JetBrains.
• AWS SAM CLI — l'outil en ligne de commande qui crée les images Docker et déploie les fonctions Lambda. Installez-le en suivant le guide d'installation SAM CLI.
• Docker Desktop — nécessaire car la fonction Lambda est emballée sous forme d'image de conteneur, et non d'archive Zip. Téléchargez Docker Community Edition.

Pour le test d'invocation local avant de déployer sur AWS, installez également :

• Java 8 JDK — disponible sur la page de téléchargement d'Oracle JDK 8.
• Apache Maven — suivez le guide d'installation de Maven.

Une fois tous les outils en place, ouvrez IntelliJ IDEA et créez un nouveau projet via Fichier → Nouveau → Projet. Dans l'assistant de projet, sélectionnez le modèle AWS Lambda et choisissez les options suivantes :

• Type de package : Image
• Runtime: java8 or java11
• Modèle SAM : Maven

Pourquoi devez-vous utiliser Docker au lieu du déploiement Zip ?

AWS Lambda prend en charge deux types de paquets de déploiement : les archives Zip et les images de conteneur. Le déploiement par Zip fonctionne bien pour les fonctions Java légères car l'environnement d'exécution est entièrement géré par AWS. IronPDF, cependant, livre un binaire natif — un moteur de rendu PDF à base de Chrome — qui doit être extrait et exécuté à l'exécution. L'environnement d'exécution Lambda pour les déploiements Zip restreint les écritures aux systèmes de fichiers à /tmp, et la couche de package Zip limite les extractions de gros binaires natifs.

Le déploiement d'image de conteneur supprime ces restrictions. Lorsque vous définissez votre propre image Docker, vous contrôlez le système d'exploitation de base, les paquets système installés et la disposition du répertoire. Le moteur de rendu d'IronPDF peut être extrait à /tmp au démarrage, les bibliothèques système nécessaires peuvent être pré-installées dans l'image, et la limite de taille du conteneur (10 Go) est assez grande pour accueillir le moteur complet.

La conséquence pratique est simple : définissez PackageType: Image dans template.yaml et construisez en utilisant une image de base compatible Docker. Le SAM CLI s'occupe du reste.

Comment configurer les dépendances Maven ?

Le fichier pom.xml nécessite trois catégories de dépendances supplémentaires au-delà du SDK Lambda standard : la bibliothèque Java IronPDF, le moteur de rendu Linux x64 IronPDF et le transport gRPC utilisé en interne par le moteur IronPDF.

Ouvrez pom.xml et ajoutez les dépendances suivantes à l'intérieur 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>

Le fichier d'artefact ironpdf-engine-linux-x64 regroupe le moteur de rendu basé sur Chromium pré-compilé pour Linux 64 bits. C'est ce qui permet à IronPDF de rendre du HTML en PDF à l'intérieur du conteneur Lambda. Sans cela, les appels de rendu échoueront avec une erreur de binaire manquant. Les dépendances gRPC (grpc-okhttp, grpc-netty-shaded, perfmark-api) sont requises car IronPDF communique avec son moteur de rendu via un canal gRPC local. La dépendance slf4j-simple fournit une implémentation minimale de journalisation permettant de rendre les journaux internes de l'IronPDF visibles dans CloudWatch.

Alignez toujours les numéros de versions ironpdf et ironpdf-engine-linux-x64 — un mélange de versions entraînera un échec au démarrage. Vérifiez IronPDF for Java sur Maven Central pour la dernière version.

Comment écrire le gestionnaire Lambda ?

La classe gestionnaire Lambda reçoit un APIGatewayProxyRequestEvent, génère un PDF, et retourne un APIGatewayProxyResponseEvent. Deux appels de configuration IronPDF doivent apparaître avant la première opération de rendu : régler le répertoire de travail sur /tmp et éventuellement activer la journalisation de débogage.

Remplacez le contenu de App.java par ce qui suit :

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

L'appel à Settings.setIronPdfEngineWorkingDirectory(Paths.get("/tmp/")) est obligatoire. L'environnement d'exécution AWS Lambda monte le code de la fonction dans un répertoire en lecture seule. Le moteur IronPDF doit extraire les fichiers de support et créer des sockets au démarrage — des activités qui nécessitent un accès en écriture. Le répertoire /tmp est le seul emplacement que Lambda permet pour les écritures de fichiers, donc IronPDF doit y être orienté avant de commencer tout rendu. Si ce paramètre est omis, le moteur échouera à démarrer et chaque appel de rendu jettera une exception.

L'appel à pdf.saveAs("/tmp/output.pdf") stocke le fichier rendu dans le système de fichiers éphémère /tmp. Si la fonction Lambda doit retourner le PDF comme une réponse binaire ou le télécharger vers S3, récupérez les octets avec pdf.getBinaryData() au lieu d'écrire sur le disque. Pour les charges de travail à grande échelle, le téléchargement vers Amazon S3 et le retour d'une URL pré-signée est le modèle recommandé.

Comment configurer le modèle SAM ?

Le fichier template.yaml contrôle l'allocation des ressources de la fonction Lambda. Trois paramètres affectent directement si IronPDF fonctionne correctement : Timeout, MemorySize, et EphemeralStorage.Size.

Mettez à jour la section Globals de template.yaml comme suit :

//: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 est réglé sur 400 secondes. Au démarrage à froid, IronPDF doit extraire le moteur de rendu à /tmp et lancer un processus Chromium local. Cette extraction peut prendre 30 à 60 secondes lors de la première invocation. Un délai d'expiration inférieur à 330 secondes entraînera l'échec des invocations à froid avec une erreur de délai d'expiration de tâche. Les invocations chaudes sont beaucoup plus rapides — généralement moins de 5 secondes pour des conversions HTML en PDF simples.

MemorySize est réglé sur 2048 Mo. Le rendu Chromium est gourmand en mémoire. La mémoire minimale viable d'AWS Lambda pour IronPDF est de 1024 Mo, mais 2048 Mo réduisent le risque d'échecs dus au manque de mémoire pour les pages complexes et permettent des temps de rendu sensiblement plus rapides car Lambda évolue également l'allocation CPU proportionnellement avec la mémoire.

EphemeralStorage.Size est réglé sur 1024 Mo. L'allocation par défaut de /tmp pour Lambda est de 512 Mo. IronPDF écrit les binaires du moteur de rendu, le cache des polices, et les fichiers de rendu temporaires à /tmp. Ces actifs peuvent dépasser 512 Mo au démarrage à froid, ce qui provoque l'échec de l'extraction du moteur. Régler le stockage éphémère à au moins 1024 Mo prévient ce mode d'échec.

Comment créer le fichier Dockerfile ?

Le Dockerfile est le cœur de ce déploiement. Il effectue une construction à plusieurs étapes : la première étape compile le projet Java en utilisant une image de construction Maven ; la seconde étape crée l'image d'exécution Lambda finale basée sur Amazon Linux 2, installe les paquets système requis par le moteur Chromium d'IronPDF, et copie les artefacts compilés.

Ouvrez le Dockerfile du projet et remplacez son contenu par le suivant :

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

Les images de base pour les deux étapes utilisent le tag java8.al2 plutôt que le simple java8. Le suffixe .al2 indique Amazon Linux 2, qui est requis pour IronPDF. L'ancienne image de java8 s'exécute sur le Linux d'Amazon 1 original, qui utilise des dépôts yum qui ne reçoivent plus de mises à jour et manquent de plusieurs paquets dont IronPDF dépend. Utilisez toujours les images .al2 lors du déploiement d'IronPDF sur Java 8.

Le bloc yum install installe les bibliothèques X11, GTK3, Pango et liées aux polices dont Chromium a besoin pour rendre les pages. Omission de l'un de ces paquets peut produire une sortie PDF incomplète ou provoquer le crash du moteur de rendu avec une erreur de bibliothèque partagée manquante. Le package libgdiplus est nécessaire pour la compatibilité avec GDI+, qui est utilisée par certaines opérations de dessin d'IronPDF.

Mettez à jour l'instruction CMD pour qu'elle corresponde à votre nom de package et de classe réel s'ils diffèrent de helloworld.App.

Comment créer et déployer la fonction Lambda ?

Avec le Dockerfile, template.yaml, pom.xml, et App.java tous configurés, exécutez les deux commandes SAM CLI suivantes depuis la racine du projet.

Étape 1 — Construire l'image du conteneur :

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

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

Le drapeau -u ordonne à SAM d'utiliser Docker (le mode "utiliser le conteneur"). SAM exécute le Dockerfile à plusieurs étapes, compile le projet Maven et produit l'image finale Lambda. Attendez-vous à ce que cette étape prenne plusieurs minutes lors de la première exécution tandis que Docker télécharge les images de base.

Étape 2 — Déployer sur AWS :

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

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

Le drapeau --guided lance une invite interactive qui demande le nom de la pile, la région AWS, le bucket S3 pour les artefacts, et si vous souhaitez confirmer les jeux de modifications avant le déploiement. Répondez aux invites, et SAM poussera l'image du conteneur vers Amazon ECR et créera la fonction Lambda, l'API Gateway, et le rôle IAM défini dans template.yaml.

Une fois le déploiement terminé, le SAM CLI affiche l'URL du point d'accès API. Ouvrez la Console AWS Lambda pour voir la fonction déployée, exécuter des invocations de test, et inspecter les journaux CloudWatch pour la sortie de débogage IronPDF.

Lors de la première invocation (démarrage à froid), attendez un temps de réponse de 60 à 120 secondes pendant que l'environnement d'exécution Lambda démarre et qu'IronPDF extrait son moteur de rendu à /tmp. Les invocations suivantes sur le même instance chaude retourneront en quelques secondes. Si la latence de démarrage à froid est une préoccupation pour les charges de travail de production, envisagez d'utiliser Lambda Provisioned Concurrency pour garder les instances chaudes.

Vous pouvez également tester la fonction localement avant de déployer en exécutant sam local invoke avec une charge utile d'événement de test, à condition que Docker fonctionne sur la machine de développement.

Quelles sont les prochaines étapes?

La fonction Lambda est maintenant déployée et rend des PDFs. Les guides suivants couvrent les étapes les plus courantes après un déploiement réussi d'IronPDF :

• IronPDF for Java — Démarrage — vue d'ensemble de l'API complète IronPDF Java, y compris HTML en PDF, URL en PDF, et estampillage de PDF.
• Comment générer des PDFs à partir de HTML en Java — rendu de chaînes, fichiers et modèles HTML en PDF.
• Comment appliquer des en-têtes et pieds de page aux PDFs en Java — ajout de numéros de page, de logos, et d'en-têtes de texte aux PDFs générés par Lambda.
• Comment ajouter des filigranes aux PDFs en Java — estampillage de la sortie PDF avec des filigranes de texte ou d'image avant de les retourner à l'appelant.
• Licences IronPDF — options de licence pour les déploiements Lambda en production, y compris le licensing basé sur le nombre de déploiements.

Commencez une évaluation gratuite d'IronPDF for Java pour générer et éditer des PDFs dans votre fonction Lambda sans restrictions pendant l'évaluation. Lorsque vous êtes prêt à déployer en production, consultez les options de licences IronPDF pour trouver le plan qui correspond à votre charge de travail sans serveur.