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? {#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:

• Paket-Typ: Image
• Laufzeit: java8 oder java11
• SAM-Vorlage: Maven

Warum müssen Sie Docker anstelle der Zip-Bereitstellung verwenden? {#why-docker}

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 eine native Binärdatei – 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 Schreibvorgänge im Dateisystem auf /tmp, und die Beschränkungen der ZIP-Paketebene verhindern die Extraktion großer nativer Binärdateien.

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 in /tmp extrahiert werden, die erforderlichen Systembibliotheken können im Image vorinstalliert werden, und die Containergrößenbeschränkung (10 GB) ist groß genug, um die gesamte Engine aufzunehmen.

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

Wie konfigurieren Sie die Maven-Abhängigkeiten? {#Maven-dependencies}

Die Datei pom.xml benötigt drei Kategorien zusätzlicher Abhängigkeiten, die über das Standard-Lambda-SDK hinausgehen: 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 vorkompilierte 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) sind erforderlich, 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.

Richten Sie die Versionsnummern ironpdf und ironpdf-engine-linux-x64 stets aufeinander ab – eine Vermischung der Versionen führt zu einem Startfehler. Informieren Sie sich auf IronPDF for Java bei Maven Central nach der neuesten Versionszeichenfolge.

Wie schreiben Sie den Lambda-Handler? {#lambda-handler}

Die Lambda-Handler-Klasse empfängt ein APIGatewayProxyRequestEvent, generiert eine PDF-Datei und gibt ein APIGatewayProxyResponseEvent zurück. Vor dem ersten Rendering-Vorgang müssen zwei IronPDF-Konfigurationsaufrufe erfolgen: das Festlegen des Arbeitsverzeichnisses auf /tmp und optional das Aktivieren der Debug-Protokollierung.

Ersetzen Sie den Inhalt von App.java durch Folgendes:

//: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 Verzeichnis /tmp ist der einzige Ort, an dem Lambda das Schreiben von Dateien zulässt, daher muss IronPDF dorthin verweisen, bevor mit der Darstellung begonnen wird. Wenn diese Einstellung weggelassen wird, startet die Engine nicht und jeder Rendering-Aufruf wirft eine Ausnahme.

Der Aufruf pdf.saveAs("/tmp/output.pdf") speichert die gerenderte Datei im temporären Dateisystem /tmp. Wenn die Lambda-Funktion die PDF-Datei als binäre Antwort zurückgeben oder auf S3 hochladen soll, rufen Sie die Bytes mit pdf.getBinaryData() ab, anstatt sie 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? {#sam-template}

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

Aktualisieren Sie den Abschnitt Globals 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 nach /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 Standardzuweisung für Lambda /tmp beträgt 512 MB. IronPDF schreibt die Binärdateien der Rendering-Engine, den Font-Cache und temporäre Rendering-Dateien in /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? {#dockerfile}

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 Datei Dockerfile des Projekts und ersetzen Sie deren Inhalt durch Folgendes:

//: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 Tag java8.al2 anstelle des einfachen java8. Das Suffix .al2 steht für Amazon Linux 2, das für IronPDF erforderlich ist. Das ältere java8-Image läuft auf dem ursprünglichen Amazon Linux 1, das yum-Repositorys verwendet, die keine Updates mehr erhalten und in denen mehrere Pakete fehlen, von denen IronPDF abhängt. Verwenden Sie bei der Bereitstellung von IronPDF unter Java 8 immer .al2-Bilder.

Der Block yum install installiert die Bibliotheken X11, GTK3, Pango und die fontbezogenen Bibliotheken, die Chromium zum Rendern von Seiten benötigt. 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 die GDI+-Kompatibilität benötigt, die von einigen IronPDF-Zeichenoperationen verwendet wird.

Passen Sie die Anweisung CMD an Ihren tatsächlichen Paket- und Klassennamen an, falls diese von helloworld.App abweichen.

Wie erstellen und bereitstellen Sie die Lambda-Funktion? {#build-deploy}

Nachdem die Dockerfile, template.yaml, pom.xml und App.java konfiguriert sind, führen Sie die folgenden beiden SAM-CLI-Befehle vom Projektstammverzeichnis aus.

Schritt 1 — Erstellen Sie das Container-Image:

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

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

Das Flag -u weist SAM an, Docker zu verwenden (den Modus "use container"). 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 Flag --guided öffnet eine interaktive Eingabeaufforderung, in der nach dem Stack-Namen, der AWS-Region, dem S3-Bucket für Artefakte und der Frage gefragt wird, ob Changesets vor der Bereitstellung bestätigt werden sollen. 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.

Beim ersten Aufruf (Kaltstart) ist mit einer Antwortzeit von 60–120 Sekunden zu rechnen, da die Lambda-Ausführungsumgebung startet und IronPDF seine Rendering-Engine in /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 vor der Bereitstellung auch lokal testen, indem Sie sam local invoke mit einer Test-Event-Nutzlast ausführen, vorausgesetzt, Docker läuft auf dem Entwicklungsrechner.

Was sind die nächsten Schritte? {#next-steps}

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.