Java için AWS'de IronPDF Nasıl Kurulur

İçindekiler

• Ön Gereksinimler Nedir?
• Neden Docker kullanmalıyız, zip dağıtımı yerine?
• Maven Bağımlılıklarını Nasıl Yapılandırırsınız?
• Lambda İşleyicisi Nasıl Yazılır?
• SAM Şablonu Nasıl Yapılandırılır?
• Dockerfile Nasıl İnşa Edilir?
• Lambda Fonksiyonu Nasıl Derlenir ve Dağıtılır?
• Sonraki Adımlar Neler?

Ön Gereksinimler Nedir? {#önkoşullar}

Başlamadan önce, geliştirme makinesinde aşağıdaki araçların kurulu olduğunu doğrulayın. Her araç, inşa-et ve dağıt boru hattında özel bir rol oynamaktadır.

• IntelliJ IDEA — bu kılavuzda kullanılan IDE. jetbrains.com/idea adresinden indirin.
• JetBrains için AWS Araçları — IntelliJ içinde SAM proje sihirbazı ve Lambda çalıştırma yapılandırmaları sağlar. JetBrains için AWS Araçları belgeleri sayfasında kurulum talimatları bulunmaktadır.
• AWS SAM CLI — Docker imajları oluşturup Lambda fonksiyonlarını dağıtan komut satırı aracı. SAM CLI kurulum kılavuzunu takip ederek yükleyin.
• Docker Desktop — gerekli çünkü Lambda fonksiyonu bir konteyner imajı olarak paketlenmiş, bir Zip arşivi değil. Docker Topluluk Sürümünü indirin.

AWS'ye dağıtmadan önce yerel çağrı testi için, ayrıca şunları yükleyin:

• Java 8 JDK — Oracle JDK 8 indirme sayfasından elde edilebilir.
• Apache Maven — Maven kurulum kılavuzunu takip edin.

Tüm araçlar yerine oturduğunda, IntelliJ IDEA'yı açın ve File → New → Project yoluyla yeni bir proje oluşturun. Proje sihirbazında, AWS Lambda şablonunu seçin ve aşağıdaki seçenekleri tercih edin:

• Paket Türü: Image
• Çalışma Zamanı: java8 veya java11
• SAM Şablonu: Maven

Neden Docker kullanmalıyız, zip dağıtımı yerine? {#why-docker}

AWS Lambda, iki dağıtım paketi türünü destekler: Zip arşivleri ve kapsayıcı imajlar. Zip dağıtımı, hafif Java fonksiyonları için iyi çalışır çünkü çalışma zamanı ortamı tamamen AWS tarafından yönetilir. Ancak, IronPDF, yerel bir ikili dosya — Chrome tabanlı bir PDF render motoru — gönderir, bu da çalışma zamanında çıkartılmalı ve çalıştırılmalıdır. Zip dağıtımları için Lambda yürütme ortamı dosya sistemi yazmalarını /tmp ile sınırlar ve Zip paket katmanı sınırlamaları büyük yerel ikili dosyaların çıkartılmasını önler.

Kapsayıcı imaj dağıtımı bu kısıtlamaları ortadan kaldırır. Kendi Docker imajınızı tanımladığınızda, taban işletim sistemi, yüklenen sistem paketleri ve dizin düzeni üzerinde kontrol sahibi olursunuz. IronPDF'ın render motoru başlangıçta /tmp'ya çıkartılabilir, gerekli sistem kütüphaneleri görüntüde önceden yüklenebilir ve kapsayıcı boyutu limiti (10 GB) tam motoru barındırmak için yeterince büyüktür.

Pratik sonuç basittir: PackageType: Image'yi template.yaml'da ayarlayın ve Docker-uyumlu bir temel görüntü kullanarak oluşturun. SAM CLI gerisini ele alır.

Maven Bağımlılıklarını Nasıl Yapılandırırsınız? {#maven-dependencies}

pom.xml dosyası, standart Lambda SDK'sının yanı sıra üç ek bağımlılık kategorisi gerektirir: IronPDF Java kütüphanesi, IronPDF Linux x64 rendering motoru ve IronPDF motoru tarafından dahili olarak kullanılan gRPC taşımacılığı.

pom.xml'yu açın ve <dependencies> içinde aşağıdaki bağımlılıkları ekleyin:

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

ironpdf-engine-linux-x64 artifact'i 64-bit Linux için önceden derlenmiş Chromium tabanlı render motorunu paketler. Bu, IronPDF'nin Lambda konteyneri içinde HTML'i PDF'ye dönüştürmesini sağlar. Olmadan, işleme çağrıları eksik ikili hata ile başarısız olur. IronPDF'in render motoru ile yerel bir gRPC kanalı üzerinden iletişim kurduğu için gRPC bağımlılıkları (grpc-okhttp, grpc-netty-shaded, perfmark-api) gereklidir. slf4j-simple bağımlılığı, IronPDF'in dahili günlüklerinin CloudWatch'ta görünür olması için minimal bir loglama uygulaması sağlar.

ironpdf ve ironpdf-engine-linux-x64 sürüm numaralarını her zaman hizalayın — sürümlerin karıştırılması başlatma hatasına neden olur. Maven Central'da IronPDF for Java sayfasını en son sürüm dizesi için kontrol edin.

Lambda İşleyicisini Nasıl Yazarsınız? {#lambda-handler}

Lambda işleyici sınıfı bir APIGatewayProxyRequestEvent alır, bir PDF oluşturur ve bir APIGatewayProxyResponseEvent döndürür. İlk render işlemi öncesinde iki IronPDF yapılandırma çağrısı görünmelidir: çalışma dizinini /tmp olarak ayarlamak ve isteğe bağlı olarak hata ayıklama logging'ini etkinleştirmek.

App.java içeriğini aşağıdakilerle değiştirin:

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

Settings.setIronPdfEngineWorkingDirectory(Paths.get("/tmp/")) çağrısı zorunludur. AWS Lambda'nın yürütme ortamı işlev kodunu salt okunur bir dizine monte eder. IronPDF motoru, başlangıçta destek dosyalarını çıkarmalı ve soketler oluşturmalıdır — yazma erişimi gerektiren etkinlikler. /tmp dizini, Lambda'nın dosya yazımına izin verdiği tek yerdir, bu nedenle IronPDF, herhangi bir render işlemine başlamadan önce oraya yönlendirilmelidir. Bu ayar atlandığında, motor başlayamaz ve her render çağrısı bir istisna fırlatır.

pdf.saveAs("/tmp/output.pdf") çağrısı işlenmiş dosyayı geçici /tmp dosya sistemine depolar. Lambda işlevi PDF'yi bir ikili yanıt olarak döndürmek veya S3'ye yüklemek zorundaysa, disk yazmak yerine pdf.getBinaryData() ile baytları alın. Büyük ölçekli iş yükleri için, Amazon S3'ye yükleme ve ön imzalı bir URL döndürme önerilen modeldir.

SAM Şablonunu Nasıl Yapılandırırsınız? {#sam-template}

template.yaml dosyası Lambda fonksiyonunun kaynak tahsisini kontrol eder. Üç ayar, IronPDF'in başarılı şekilde çalışıp çalışmadığını doğrudan etkiler: Timeout, MemorySize ve EphemeralStorage.Size.

Globals bölümünü template.yaml içindeki aşağıdaki gibi güncelleyin:

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

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

Zaman Aşımı 400 saniyeye ayarlanmış. Soğuk başlatmada, IronPDF render motorunu /tmp'ye çıkarmalı ve yerel bir Chromium sürecini başlatmalıdır. Bu çıkarma, ilk çağrıda 30-60 saniye sürebilir. 330 saniyeden daha kısa bir zaman aşımı, soğuk başlangıç çağrılarının görev zaman aşımı hatasıyla başarısız olmasına neden olur. Sıcak çağrılar çok daha hızlıdır — genellikle basit HTML'den PDF'ye dönüşümler için 5 saniyeden kısadır.

Hafıza Boyutu 2048 MB olarak ayarlanmış. Chromium işleyici hafıza yoğundur. AWS Lambda için IronPDF'nin minimum uygun hafızası 1024 MB'tır, ancak 2048 MB karmaşık sayfalar için bellek yetersizliği hatalarının riskini azaltır ve fark edilir şekilde daha hızlı dönüş süreleri sağlar çünkü Lambda, bellekle orantılı olarak CPU tahsisatını da ölçeklendirir.

EphemeralStorage.Size 1024 MB olarak ayarlanır. Varsayılan Lambda /tmp tahsisi 512 MB'dir. IronPDF render motoru ikili dosyalarını, yazı tipi önbelleğini ve geçici render dosyalarını /tmp'ye yazar. Bu varlıklar, soğuk başlangıçta 512 MB'yi aşabilir ve bu da motor çıkarımın başarısız olmasına neden olur. Ephemeral depolamayı en az 1024 MB olarak ayarlamak bu hata modunu önler.

Dockerfile'ı Nasıl Oluşturursunuz? {#dockerfile}

Dockerfile bu dağıtımın kalbidir. Çok aşamalı bir yapım gerçekleştirir: ilk aşama, Maven derleme görüntüsü kullanarak Java projesini derler; ikinci aşama, Amazon Linux 2 tabanlı nihai Lambda çalışma zamanı görüntüsünü oluşturur, IronPDF'nin Chromium motorunun gerektirdiği sistem paketlerini kurar ve derlenmiş eserleri kopyalar.

Projenin Dockerfile dosyasını açın ve içeriğini aşağıdaki ile değiştirin:

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

Her iki aşama için temel görüntüler, düz java8 yerine java8.al2 etiketini kullanır. .al2 eki Amazon Linux 2'yi belirtir ve bu IronPDF için gereklidir. Daha eski java8 görüntüsü, artık güncellemeler almayan ve IronPDF'in bağımlı olduğu birkaç paketten yoksun olan orijinal Amazon Linux 1 üzerinde çalışır. Her zaman .al2 görüntülerini IronPDF'i Java 8 üzerine dağıtırken kullanın.

yum install bloğu Chromium'un sayfaları render edebilmesi için gerekli olan X11, GTK3, Pango ve yazı tipleriyle ilgili kütüphaneleri yükler. Bu paketlerden herhangi birinin ihmal edilmesi, eksik PDF çıktısı oluşturabilir veya render motorunun eksik paylaşılan kütüphane hatasıyla çökmesine neden olabilir. libgdiplus paketi bazı IronPDF çizim işlemleri için kullanılan GDI+ uyumluluğu için gereklidir.

CMD talimatını, gerçek paket ve sınıf isimleriniz helloworld.App'da farklıysa, bunlarla eşleştirilecek şekilde güncelleyin.

Lambda Fonksiyonunu Nasıl Kurar ve Dağıtırsınız? {#build-deploy}

Dockerfile, template.yaml, pom.xml ve App.java tümü yapılandırıldıktan sonra, proje kök dizininden aşağıdaki iki SAM CLI komutunu çalıştırın.

Adım 1 — Konteyner imajını oluşturun:

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

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

-u bayrağı, SAM'e Docker'ı kullanmasını ("kapsayıcı kullanma" modu) talimat verir. SAM, Maven projesini derleyen ve nihai Lambda görüntüsünü üreten çok aşamalı Dockerfile'ı yürütür. Docker ilk etapta temel görüntüleri çekerken bu adımın birkaç dakika sürebileceğinden onaylayın.

Adım 2 — AWS'ye Dağıt:

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

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

--guided bayrağı, etkileşimli bir istem açar ve burada yığın adını, AWS bölgesini, eserler için S3 kovası ve dağıtımdan önce değişiklik kümeleri doğrulansın mı diye bir prompt alırsınız. Promptlara cevap verin, SAM kapsayıcı imajını Amazon ECR'e itecek ve template.yaml içinde tanımlanan Lambda işlevini, API Gateway'i ve IAM rolünü oluşturacaktır.

Dağıtım tamamlandıktan sonra, SAM CLI API uç nokta URL'sini çıktı olarak verir. Dağıtılan işlevi görmek, test çağrılarını çalıştırmak ve IronPDF hata ayıklama çıktısı için CloudWatch günlüklerini incelemek için AWS Lambda Konsolunu açın.

İlk çağrıda (soğuk başlatma), Lambda yürütme ortamı başladığından ve IronPDF render motorunu /tmp'ye çıkardığından yanıt süresi olarak 60–120 saniye bekleyin. Aynı sıcak örnek üzerindeki sonraki çağrılar birkaç saniye içinde dönecektir. Üretim iş yükleri için soğuk başlatma gecikmesi bir endişe ise, Lambda Provisioned Concurrency kullanarak örnekleri sıcak tutmayı düşünün.

Docker geliştirme makinesinde çalışıyorsa, test olayı yüküyle sam local invoke çalıştırarak dağıtımdan önce fonksiyonu yerel olarak da test edebilirsiniz.

Bir Sonraki Adımlar Nelerdir? {#next-steps}

Lambda fonksiyonu şimdi dağıtılmış ve PDF'leri render ediyor. IronPDF'nin başarılı bir dağıtımından sonraki en yaygın sonraki adımları kapsayan kılavuzlar şunlardır:

• IronPDF for Java — Başlarken — HTML to PDF, URL to PDF ve PDF damgalaması dahil olmak üzere tam IronPDF Java API'sinin genel bir bakış.
• Java'da HTML'den PDF'ye PDF'ler Nasıl Oluşturulur — Strimg, dosya ve şablonları PDF'ye render etme.
• Java'da PDF'lere Üst Bilgi ve Alt Bilgiler Nasıl Uygulanır — Sayfa numaraları, logolar ve metin üst bilgileri Lambda tarafından oluşturulan PDF'lere ekleme.
• Java'da PDF'lere Filigranlar Nasıl Eklenir — PDF çıktısını metin veya resim filigranları ile damgalayarak arayana iade etmeden önce.
• IronPDF Lisanslama — Üretim Lambda dağıtımları için dağıtım sayısı lisans seçenekleri dahil olmak üzere lisans seçenekleri.

IronPDF for Java ücretsiz deneme başlatın ve değerlendirme süresince sınırlama olmaksızın Lambda işlevinizde PDF'ler oluşturup düzenleyin. Üretime dağıtmaya hazır olduğunuzda, IronPDF lisanslama seçeneklerini görüntüleyin ve sunucusuz iş yüküne uygun planı bulun.