Spis treści

• Jakie są wymagania wstępne?
• Dlaczego musisz używać Docker zamiast wdrożenia Zip?
• Jak skonfigurować zależności Maven?
• Jak napisać obsługę Lambda?
• Jak skonfigurować szablon SAM?
• Jak utworzyć Dockerfile?
• Jak utworzyć i wdrożyć funkcję Lambda?
• Jakie są kolejne kroki?

Jakie są wymagania wstępne? {#prerequisites}

Przed rozpoczęciem upewnij się, że następujące narzędzia są zainstalowane na maszynie deweloperskiej. Każde z narzędzi odgrywa określoną rolę w potoku tworzenia i wdrażania.

• IntelliJ IDEA — IDE używane w tym przewodniku. Pobierz z jetbrains.com/idea.
• AWS Toolkit for JetBrains — zapewnia kreatora projektów SAM i konfiguracje uruchomienia Lambda w środowisku IntelliJ. Instrukcje konfiguracji znajdują się na stronie dokumentacji AWS Toolkit for JetBrains.
• AWS SAM CLI — narzędzie wiersza poleceń, które buduje obrazy Docker i wdraża funkcje Lambda. Zainstaluj, korzystając z SAM CLI installation guide.
• Docker Desktop — wymagany, ponieważ funkcja Lambda jest pakowana jako obraz kontenera, a nie archiwum Zip. Pobierz Docker Community Edition.

Do testowania lokalnego uruchomienia przed wdrożeniem na AWS, zainstaluj także:

• Java 8 JDK — dostępne na stronie pobierania Oracle JDK 8.
• Apache Maven — postępuj zgodnie z instrukcjami instalacji Maven.

Gdy wszystkie narzędzia są dostępne, otwórz IntelliJ IDEA i stwórz nowy projekt przez File → New → Project. W kreatorze projektów wybierz szablon AWS Lambda i wybierz następujące opcje:

• Typ pakietu: Image
• Środowisko uruchomieniowe: java8 lub java11
• Szablon SAM: Maven

Dlaczego musisz używać Docker zamiast wdrożenia Zip? {#why-docker}

AWS Lambda obsługuje dwa typy pakietów wdrożeniowych: archiwa Zip i obrazy kontenerów. Wdrożenie Zip działa dobrze dla lekkich funkcji Javy ponieważ środowisko uruchomieniowe jest całkowicie zarządzane przez AWS. IronPDF zawiera jednak natywny plik binarny — silnik renderowania plików PDF oparty na przeglądarce Chrome — który musi zostać wyodrębniony i uruchomiony w czasie wykonywania. Środowisko wykonawcze Lambda dla wdrożeń ZIP ogranicza zapisy w systemie plików do /tmp, a ograniczenia warstwy pakietu ZIP uniemożliwiają wyodrębnianie dużych plików binarnych.

Wdrożenie obrazu kontenera usuwa te ograniczenia. Definiując własny obraz Dockera, kontrolujesz bazowy system operacyjny, zainstalowane pakiety systemowe i układ katalogów. Silnik renderujący IronPDF można wyodrębnić do /tmp podczas uruchamiania, wymagane biblioteki systemowe można wstępnie zainstalować w obrazie, a limit rozmiaru kontenera (10 GB) jest wystarczająco duży, aby pomieścić cały silnik.

W praktyce oznacza to po prostu: ustaw PackageType: Image w template.yaml i skompiluj przy użyciu obrazu bazowego obsługującego Docker. SAM CLI zajmuje się resztą.

Jak skonfigurować zależności Maven? {#Maven-dependencies}

Plik pom.xml wymaga trzech kategorii dodatkowych zależności poza standardowym zestawem Lambda SDK: biblioteki IronPDF for Java, silnika renderującego IronPDF dla systemu Linux x64 oraz transportu gRPC używanego wewnętrznie przez silnik IronPDF.

Otwórz pom.xml i dodaj następujące zależności wewnątrz <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>

Artefakt ironpdf-engine-linux-x64 zawiera wstępnie skompilowany silnik renderujący oparty na Chromium dla 64-bitowego systemu Linux. To umożliwia IronPDF renderowanie HTML na PDF wewnątrz kontenera Lambda. Bez tego wywołania renderowania zakończą się niepowodzeniem z błędem brakującego binarnego pliku. Zależności gRPC (grpc-okhttp, grpc-netty-shaded, perfmark-api) są wymagane, ponieważ IronPDF komunikuje się ze swoim silnikiem renderującym za pośrednictwem lokalnego kanału gRPC. Zależność slf4j-simple zapewnia minimalną implementację logowania, dzięki czemu wewnętrzne logi IronPDF są widoczne w CloudWatch.

Zawsze należy dopasować numery wersji ironpdf i ironpdf-engine-linux-x64 — mieszanie wersji spowoduje błąd podczas uruchamiania. Sprawdź IronPDF dla Java na Maven Central, aby uzyskać najnowszy ciąg wersji.

Jak napisać obsługę Lambda? {#lambda-handler}

Klasa obsługi Lambda odbiera APIGatewayProxyRequestEvent, generuje plik PDF i zwraca APIGatewayProxyResponseEvent. Przed pierwszą operacją renderowania muszą pojawić się dwa wywołania konfiguracyjne IronPDF: ustawienie katalogu roboczego na /tmp oraz opcjonalne włączenie logowania debugowania.

Zastąp zawartość App.java następującym tekstem:

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

Wywołanie Settings.setIronPdfEngineWorkingDirectory(Paths.get("/tmp/")) jest obowiązkowe. Środowisko wykonawcze AWS Lambda montuje kod funkcji w katalogu tylko do odczytu. Silnik IronPDF musi wyodrębnić pliki wsparcia oraz stworzyć gniazda podczas uruchamiania — czynności te wymagają dostępu do zapisu. Katalog /tmp jest jedyną lokalizacją, w której Lambda zezwala na zapisywanie plików, więc przed rozpoczęciem renderowania należy skierować IronPDF właśnie tam. Jeśli to ustawienie zostanie pominięte, silnik nie zainicjuje się i każde wywołanie renderowania rzuci wyjątkiem.

Wywołanie pdf.saveAs("/tmp/output.pdf") zapisuje wyrenderowany plik w tymczasowym systemie plików /tmp. Jeśli funkcja Lambda musi zwrócić plik PDF jako odpowiedź binarną lub przesłać go do S3, pobierz bajty za pomocą pdf.getBinaryData() zamiast zapisywać je na dysku. Dla zadań na dużą skalę zalecanym wzorcem jest przesyłanie do Amazon S3 i zwracanie wstępnie podpisanego adresu URL.

Jak skonfigurować szablon SAM? {#sam-template}

Plik template.yaml kontroluje alokację zasobów funkcji Lambda. Trzy ustawienia mają bezpośredni wpływ na to, czy IronPDF działa poprawnie: Timeout, MemorySize i EphemeralStorage.Size.

Zaktualizuj sekcję Globals w template.yaml w następujący sposób:

//: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 jest ustawiony na 400 sekund. Przy zimnym starcie IronPDF musi wyodrębnić silnik renderujący do /tmp i uruchomić lokalny proces Chromium. To wyodrębnienie może zająć 30–60 sekund przy pierwszym wywołaniu. Limit czasu krótszy niż 330 sekund spowoduje niepowodzenie wywołań podczas zimnego startu z błędem przekroczenia czasu zadania. Ciepłe wywołania są znacznie szybsze – zazwyczaj poniżej 5 sekund dla prostych konwersji HTML na PDF.

MemorySize jest ustawiony na 2048 MB. Renderer Chromium jest zasobożerny. Minimalna wymagana pamięć dla IronPDF w AWS Lambda to 1024 MB, ale 2048 MB zmniejsza ryzyko niepowodzenia z powodu braku pamięci dla złożonych stron oraz zauważalnie skraca czas renderowania, ponieważ Lambda również skalują przydział CPU proporcjonalnie do pamięci.

EphemeralStorage.Size jest ustawiony na 1024 MB. Domyślny przydział pamięci Lambda /tmp wynosi 512 MB. IronPDF zapisuje pliki binarne silnika renderującego, pamięć podręczną czcionek oraz tymczasowe pliki renderowania w /tmp. Te zasoby mogą przekroczyć 512 MB podczas zimnego startu, co powoduje niepowodzenie ekstrakcji silnika. Ustawienie pamięci efemerycznej na co najmniej 1024 MB zapobiega temu trybowi awarii.

Jak zbudować Dockerfile? {#dockerfile}

Dockerfile jest sercem tego wdrożenia. Wykonuje on budowę wieloetapową: pierwszy etap kompiluje projekt Java przy użyciu obrazu budowy Maven; drugi etap tworzy końcowy obraz środowiska uruchomieniowego Lambda oparty na Amazon Linux 2, instalując pakiety systemowe wymagane przez silnik Chromium IronPDF i kopiując skompilowane artefakty.

Otwórz plik Dockerfile projektu i zastąp jego zawartość następującym tekstem:

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

W obrazach bazowych dla obu etapów użyto tagu java8.al2 zamiast zwykłego java8. Sufiks .al2 oznacza system Amazon Linux 2, który jest wymagany do działania IronPDF. Starszy obraz java8 działa na oryginalnym systemie Amazon Linux 1, który korzysta z repozytoriów yum, które nie są już aktualizowane i nie zawierają kilku pakietów, od których zależy IronPDF. Zawsze używaj obrazów .al2 podczas wdrażania IronPDF na platformie Java 8.

Blok yum install instaluje biblioteki X11, GTK3, Pango oraz biblioteki związane z czcionkami, które są potrzebne Chromium do renderowania stron. Pominięcie któregokolwiek z tych pakietów może prowadzić do niepełnego wyjścia PDF lub spowodować awarię silnika renderującego z błędem braku współdzielonej biblioteki. Pakiet libgdiplus jest potrzebny do zapewnienia zgodności z GDI+, z którego korzystają niektóre operacje rysowania w IronPDF.

Zaktualizuj instrukcję CMD, aby dopasować ją do rzeczywistej nazwy pakietu i klasy, jeśli różnią się one od helloworld.App.

Jak zbudować i wdrożyć funkcję Lambda? {#build-deploy}

Po skonfigurowaniu pliku Dockerfile, template.yaml, pom.xml i App.java, uruchom następujące dwa polecenia SAM CLI z katalogu głównego projektu.

Krok 1 — Zbuduj obraz kontenera:

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

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

Flaga -u nakazuje SAM użycie Docker (tryb "użyj kontenera"). SAM uruchamia multi-etapowy Dockerfile, który kompiluje projekt Maven i tworzy końcowy obraz Lambda. Oczekuj, że ten krok zajmie kilka minut przy pierwszym uruchomieniu, gdy Docker pobiera obrazy bazowe.

Krok 2 — Wdróż do AWS:

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

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

Flaga --guided uruchamia interaktywny monit z prośbą o podanie nazwy stosu, regionu AWS, zasobnika S3 dla artefaktów oraz o potwierdzenie zestawów zmian przed wdrożeniem. Odpowiedz na pytania, a SAM prześle obraz kontenera do Amazon ECR oraz utworzy funkcję Lambda, API Gateway i rolę IAM zdefiniowaną w template.yaml.

Po zakończeniu wdrożenia SAM CLI zwraca URL punktu końcowego API. Otwórz Konsolę AWS Lambda, aby zobaczyć wdrożoną funkcję, uruchomić testowe wywołania i przejrzeć dzienniki CloudWatch dla wyjść debugowania IronPDF.

Przy pierwszym wywołaniu (zimny start) należy spodziewać się czasu odpowiedzi wynoszącego 60–120 sekund, ponieważ środowisko wykonawcze Lambda uruchamia się, a IronPDF wyodrębnia swój silnik renderujący do /tmp. Kolejne wywołania na tej samej ciepłej instancji będą trwały tylko kilka sekund. Jeśli opóźnienie zimnego startu jest problemem dla produkcyjnych obciążeń, rozważ użycie Provisioned Concurrency Lambda w celu utrzymania instancji w stanie ciepłym.

Można również przetestować tę funkcję lokalnie przed wdrożeniem, uruchamiając sam local invoke z testową zawartością zdarzenia, pod warunkiem że na komputerze deweloperskim działa Docker.

Jakie są kolejne kroki? {#next-steps}

Funkcja Lambda jest teraz wdrożona i renderuje PDF-y. Następujące przewodniki obejmują najczęstsze następne kroki po pomyślnym wdrożeniu IronPDF:

• IronPDF dla Java — Pierwsze kroki — przegląd pełnego API IronPDF dla Java, w tym HTML-na-PDF, URL-na-PDF i stempel PDF.
• Jak generować PDF-y z HTML w Java — renderowanie ciągów HTML, plików i szablonów do PDF.
• Jak stosować nagłówki i stopki do PDF w Java — dodawanie numerów stron, logo i tekstowych nagłówników do PDF generowanych przez Lambda.
• Jak dodawać znaki wodne do PDF w Java — stemplowanie wyjścia PDF znakami wodnymi przed zwróceniem do wywołującego.
• Licencjonowanie IronPDF — opcje licencji dla produkcyjnych wdrożeń Lambda, w tym licencjonowanie na liczbę wdrożeń.

Rozpocznij bezpłatny okres próbny IronPDF dla Java, aby generować i edytować PDF-y w swojej funkcji Lambda bez ograniczeń podczas oceny. Gdy będziesz gotowy do wdrożenia na produkcję, zobacz opcje licencjonowania IronPDF, aby znaleźć plan odpowiadający wymaganiom serwerless.