Einrichtung von IronPDF for Java auf AWS

Inhaltsverzeichnis

• Was sind die Voraussetzungen?
• Warum müssen Sie Docker anstelle der Zip-Bereitstellung verwenden?
• Wie konfigurieren Sie die Maven-Abhängigkeiten?
• Wie schreiben Sie den Lambda-Handler?
• Wie konfigurieren Sie die SAM-Vorlage?
• Wie erstellen Sie die Docker-Datei?
• Wie erstellen und deployen Sie die Lambda-Funktion?
• Was sind die nächsten Schritte?

Was sind die Voraussetzungen?

Bevor Sie beginnen, bestätigen Sie, dass die folgenden Werkzeuge auf der Entwicklungsmaschine installiert sind. Jedes Tool spielt eine spezifische Rolle in der Build-und-Deploy-Pipeline.

• IntelliJ IDEA — die in diesem Leitfaden verwendete IDE. Download von jetbrains.com/idea.
• AWS Toolkit for JetBrains — stellt den SAM-Projektassistenten und die Lambda-Ausführungskonfigurationen innerhalb von IntelliJ bereit. Einrichtungsanleitungen finden Sie auf der AWS Toolkit for JetBrains Dokumentationsseite.
• AWS SAM CLI — das Befehlszeilenwerkzeug, das Docker-Images erstellt und Lambda-Funktionen bereitstellt. Installieren Sie es, indem Sie die SAM CLI Installationsanleitung befolgen.
• Docker Desktop — erforderlich, da die Lambda-Funktion als Container-Image und nicht als Zip-Archiv verpackt ist. Download Docker Community Edition.

Für lokale Aufruftests vor dem Deployment zu AWS, installieren Sie auch:

• Java 8 JDK — verfügbar von der Oracle JDK 8 Download-Seite.
• Apache Maven — folgen Sie der Maven-Installationsanleitung.

Sobald alle Werkzeuge vorhanden sind, öffnen Sie IntelliJ IDEA und erstellen Sie ein neues Projekt über Datei → Neu → Projekt. Im Projektassistenten die AWS Lambda-Vorlage auswählen und folgende Optionen wählen:

• Package Type: Image
• Laufzeit: java8 oder java11
• SAM-Vorlage: Maven

Warum müssen Sie Docker anstelle der Zip-Bereitstellung verwenden?

AWS Lambda unterstützt zwei Bereitstellungspakettypen: Zip-Archive und Container-Images. Zip-Bereitstellung funktioniert gut für leichte Java-Funktionen, da die Laufzeitumgebung vollständig von AWS verwaltet wird. IronPDF liefert jedoch ein natives Binärprogramm – eine Chrome-basierte PDF-Rendering-Engine –, die zur Laufzeit extrahiert und ausgeführt werden muss. Die Lambda-Ausführungsumgebung für Zip-Bereitstellungen beschränkt Dateisystemschreibvorgänge auf /tmp, und die Zip-Paketebene verhindert die Extraktion großer nativer Binärprogramme.

Der Einsatz von Container-Images hebt diese Beschränkungen auf. Wenn Sie Ihr eigenes Docker-Image definieren, kontrollieren Sie das Basis-Betriebssystem, die installierten Systempakete und das Verzeichnislayout. Die Rendering-Engine von IronPDF kann beim Start zu /tmp extrahiert werden, die erforderlichen Systembibliotheken können im Image vorinstalliert werden, und die Container-Größenbeschränkung (10 GB) ist groß genug, um die vollständige Engine aufzunehmen.

Die praktische Konsequenz ist einfach: Setzen Sie PackageType: Image in template.yaml und erstellen Sie mithilfe eines Docker-fähigen Basis-Images. Die SAM CLI kümmert sich um den Rest.

Wie konfigurieren Sie die Maven-Abhängigkeiten?

Die pom.xml-Datei benötigt drei Kategorien zusätzlicher Abhängigkeiten gegenüber dem Standard-Lambda-SDK: die IronPDF-Java-Bibliothek, die IronPDF-Linux-x64-Rendering-Engine und den gRPC-Transport, der intern von der IronPDF-Engine verwendet wird.

Öffnen Sie pom.xml und fügen Sie die folgenden Abhängigkeiten innerhalb von <dependencies> hinzu:

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

Das ironpdf-engine-linux-x64-Artefakt bündelt die vorab kompilierte Chromium-basierte Rendering-Engine für 64-Bit-Linux. Dies ermöglicht es IronPDF, HTML zu PDF innerhalb des Lambda-Containers zu rendern. Ohne das wird das Rendering bei einem fehlenden Binärdateifehler fehlschlagen. Die gRPC-Abhängigkeiten (grpc-okhttp, grpc-netty-shaded, perfmark-api) werden benötigt, da IronPDF über einen lokalen gRPC-Kanal mit seiner Rendering-Engine kommuniziert. Die slf4j-simple-Abhängigkeit bietet eine minimale Logging-Implementierung, sodass die internen Logs von IronPDF in CloudWatch sichtbar sind.

Gleichen Sie immer die ironpdf- und ironpdf-engine-linux-x64-Versionsnummern ab – gemischte Versionen führen zu einem Startfehler. Informieren Sie sich auf IronPDF for Java bei Maven Central nach der neuesten Versionszeichenfolge.

Wie schreiben Sie den Lambda-Handler?

Die Lambda-Handler-Klasse empfängt einen APIGatewayProxyRequestEvent, generiert ein PDF und gibt einen APIGatewayProxyResponseEvent zurück. Vor der ersten Rendering-Operation müssen zwei IronPDF-Konfigurationsaufrufe erfolgen: Das Arbeitsverzeichnis auf /tmp setzen und optional das Debug-Logging aktivieren.

Ersetzen Sie den Inhalt von App.java mit dem folgenden:

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

Der Aufruf von Settings.setIronPdfEngineWorkingDirectory(Paths.get("/tmp/")) ist obligatorisch. Die Ausführungsumgebung von AWS Lambda montiert den Funktionscode in einem schreibgeschützten Verzeichnis. Die IronPDF-Engine muss Unterstützungsdateien extrahieren und Sockets beim Start erstellen — Aktivitäten, für die Schreibzugriff erforderlich ist. Das /tmp-Verzeichnis ist der einzige Ort, den Lambda für Dateischreibvorgänge zulässt; daher muss IronPDF dort hin zeigen, bevor irgendein Rendering beginnt. Wenn diese Einstellung weggelassen wird, startet die Engine nicht und jeder Rendering-Aufruf wirft eine Ausnahme.

Der pdf.saveAs("/tmp/output.pdf")-Aufruf speichert die gerenderte Datei im flüchtigen /tmp-Dateisystem. Wenn die Lambda-Funktion das PDF als binäre Antwort zurückgeben oder es an S3 hochladen muss, rufen Sie die Bytes mit pdf.getBinaryData() ab, anstatt auf die Festplatte zu schreiben. Für großräumige Arbeitslasten ist das Hochladen zu Amazon S3 und das Zurückgeben einer vorkonfigurierten URL das empfohlene Muster.

Wie konfigurieren Sie die SAM-Vorlage?

Die template.yaml-Datei steuert die Ressourcenallokation der Lambda-Funktion. Drei Einstellungen beeinflussen direkt, ob IronPDF erfolgreich ausgeführt wird: Timeout, MemorySize und EphemeralStorage.Size.

Aktualisieren Sie den Globals-Abschnitt von template.yaml wie folgt:

//: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 ist auf 400 Sekunden gesetzt. Bei einem Kaltstart muss IronPDF die Rendering-Engine zu /tmp extrahieren und einen lokalen Chromium-Prozess starten. Diese Extraktion kann beim ersten Aufruf 30–60 Sekunden dauern. Ein Timeout von weniger als 330 Sekunden führt dazu, dass Kaltstarteinsätze mit einem Aufgaben-Timeout-Fehler fehlschlagen. Warme Aufrufe sind viel schneller — typischerweise unter 5 Sekunden für einfache HTML-zu-PDF-Konvertierungen.

MemorySize ist auf 2048 MB gesetzt. Der Chromium-Renderer ist speicherintensiv. Die minimale tragfähige Speicherkapazität von AWS Lambda für IronPDF beträgt 1024 MB, aber 2048 MB reduzieren das Risiko von Speichermangel bei komplexen Seiten erheblich und produzieren spürbar schnellere Renderzeiten, da Lambda auch die CPU-Allokation proportional mit dem Speicher skaliert.

EphemeralStorage.Size ist auf 1024 MB gesetzt. Die Standard-Zuweisung für Lambda /tmp beträgt 512 MB. IronPDF schreibt die Binärdateien der Rendering-Engine, den Schriftarten-Cache und temporäre Rendering-Dateien zu /tmp. Diese Assets können bei einem Kaltstart 512 MB überschreiten, was dazu führt, dass die Engine-Extraktion fehlschlägt. Das Setzen des flüchtigen Speichers auf mindestens 1024 MB verhindert diesen Fehlermodus.

Wie erstellen Sie die Docker-Datei?

Die Docker-Datei ist das Herzstück dieses Deployments. Sie führt einen mehrstufigen Build durch: Die erste Stufe kompiliert das Java-Projekt mithilfe eines Maven-Build-Images; die zweite Stufe erstellt das endgültige Lambda-Laufzeit-Image basierend auf Amazon Linux 2, installiert die Systempakete, die die Chromium-Engine von IronPDF benötigt, und kopiert die kompilierten Artefakte.

Öffnen Sie die Dockerfile des Projekts und ersetzen Sie deren Inhalt mit dem folgenden:

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

Die Basisbilder für beide Phasen verwenden das java8.al2-Tag anstelle von reinem java8. Das .al2-Suffix zeigt Amazon Linux 2 an, das für IronPDF erforderlich ist. Das ältere java8-Image läuft auf dem ursprünglichen Amazon Linux 1, das yum-Repositories verwendet, die keine Updates mehr erhalten und mehrere Pakete fehlen, auf die IronPDF angewiesen ist. Verwenden Sie immer .al2-Images, wenn Sie IronPDF auf Java 8 bereitstellen.

Der yum install-Block installiert die X11-, GTK3-, Pango- und Schriftarten-Bibliotheken, die Chromium benötigt, um Seiten zu rendern. Das Auslassen eines dieser Pakete kann zu unvollständiger PDF-Ausgabe oder einem Absturz der Rendering-Engine durch einen Fehler einer fehlenden freigegebenen Bibliothek führen. Das libgdiplus-Paket wird für GDI+-Kompatibilität benötigt, die von einigen IronPDF-Zeichnungsoperationen verwendet wird.

Aktualisieren Sie die CMD-Anweisung so, dass sie mit Ihrem tatsächlichen Paket- und Klassennamen übereinstimmt, falls diese von helloworld.App abweichen.

Wie erstellen und bereitstellen Sie die Lambda-Funktion?

Mit der Dockerdatei, template.yaml, pom.xml, und App.java, alle konfiguriert, führen Sie die folgenden zwei SAM CLI-Befehle vom Projektstamm aus.

Schritt 1 — Erstellen Sie das Container-Image:

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

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

Das -u-Flag weist SAM an, Docker (den "Container nutzen"-Modus) zu verwenden. SAM führt die mehrstufige Docker-Datei aus, die das Maven-Projekt kompiliert und das endgültige Lambda-Image erzeugt. Erwarten Sie, dass dieser Schritt beim ersten Ausführen mehrere Minuten dauert, da Docker die Basis-Images herunterlädt.

Schritt 2 — Bereitstellung auf AWS:

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

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

Das --guided-Flag startet eine interaktive Eingabeaufforderung, die nach dem Stack-Namen, der AWS-Region, dem S3-Bucket für Artefakte und ob Änderungen vor der Bereitstellung bestätigt werden sollen, fragt. Beantworten Sie die Eingabeaufforderungen, und SAM wird das Container-Image an Amazon ECR übertragen und die in template.yaml definierte Lambda-Funktion, das API Gateway und die IAM-Rolle erstellen.

Nach Abschluss der Bereitstellung gibt das SAM CLI die API-Endpunkt-URL aus. Öffnen Sie die AWS Lambda-Konsole, um die bereitgestellte Funktion anzusehen, Testaufrufe auszuführen und CloudWatch-Logs für IronPDF-Debug-Ausgaben zu überprüfen.

Bei der ersten Ausführung (Kaltstart) erwarten Sie eine Antwortzeit von 60–120 Sekunden, da die Lambda-Ausführungsumgebung startet und IronPDF seine Rendering-Engine zu /tmp extrahiert. Nachfolgende Aufrufe auf derselben warmen Instanz kehren innerhalb weniger Sekunden zurück. Falls die Kaltstart-Latenz bei Produktionsworkloads ein Problem ist, überlegen Sie, Lambda Provisioned Concurrency zu verwenden, um Instanzen warm zu halten.

Sie können die Funktion auch lokal testen, bevor Sie sie bereitstellen, indem Sie sam local invoke mit einer Testereignisnutzlast ausführen, vorausgesetzt, Docker läuft auf dem Entwicklungsrechner.

Was sind die nächsten Schritte?

Die Lambda-Funktion ist jetzt bereitgestellt und rendert PDFs. Die folgenden Anleitungen decken die häufigsten nächsten Schritte nach einer erfolgreichen IronPDF-Bereitstellung ab:

• IronPDF for Java — Erste Schritte — Übersicht über die gesamte IronPDF Java API, einschließlich HTML-zu-PDF, URL-zu-PDF und PDF-Stempeln.
• Wie Sie PDFs aus HTML in Java generieren — Rendering von HTML-Strings, -Dateien und -Vorlagen zu PDF.
• Wie Sie Kopf- und Fußzeilen zu PDFs in Java anwenden — Hinzufügen von Seitenzahlen, Logos und Textköpfen zu von Lambda generierten PDFs.
• Wie Sie Wasserzeichen zu PDFs in Java hinzufügen — Stempeln von PDF-Ausgaben mit Text- oder Bildwasserzeichen, bevor sie an den Anrufer zurückgegeben werden.
• IronPDF-Lizenzierung — Lizenzoptionen für Produktions-Lambda-Bereitstellungen, einschließlich Lizenzierung auf Grundlage der Bereitstellungsanzahl.

Starten Sie eine kostenlose IronPDF for Java-Testversion, um PDFs in Ihrer Lambda-Funktion ohne Einschränkungen während der Bewertung zu generieren und zu bearbeiten. Sobald Sie bereit sind, in die Produktion zu gehen, sehen Sie sich die IronPDF-Lizenzierungsoptionen an, um den Plan zu finden, der zu Ihrer serverlosen Arbeitslast passt.