Docker and serverless | Aspose.Page for Java

Aspose.Page for Java is a cross-platform Java artifact. It does not require a native converter binary in the host image, but containerized deployments must still configure the JVM’s headless and font subsystems correctly.

See Installation to add Aspose.Page for Java to your project.

Docker

Migrating from a native converter

An application that currently calls a native converter may start from an image like this:

ARG JAVA_RELEASE=21
FROM eclipse-temurin:${JAVA_RELEASE}-jre-jammy

RUN apt-get update \
 && apt-get install -y --no-install-recommends \
      ghostscript \
      fontconfig \
      fonts-dejavu-core \
 && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY target/myapp.jar .
ENTRYPOINT ["java", "-jar", "myapp.jar"]

Dockerfile

With Aspose.Page, no native converter binary is needed in the image. Install fontconfig and the font files required by your documents, and enable headless mode for the JVM:

ARG JAVA_RELEASE=21
FROM eclipse-temurin:${JAVA_RELEASE}-jre-jammy

RUN apt-get update \
 && apt-get install -y --no-install-recommends \
      fontconfig \
      fonts-dejavu-core \
 && rm -rf /var/lib/apt/lists/*

ENV JAVA_TOOL_OPTIONS="-Djava.awt.headless=true"

WORKDIR /app
COPY target/myapp.jar .
ENTRYPOINT ["java", "-jar", "myapp.jar"]

Both files default to Java 21. Override JAVA_RELEASE as a build argument when your application targets a different Java release.

Two Java-specific things that will bite you

Headless mode

Aspose.Page uses java.awt types while parsing PostScript, not only when rasterizing content. Headless mode is therefore required for every operation, including a plain PS-to-PDF conversion that produces no image.

In a container, AWT may try to connect to a display unless headless mode is enabled:

-Djava.awt.headless=true

Set this as a JVM flag or through JAVA_TOOL_OPTIONS, not in application code. AWT may already have initialized before main runs.

Headless mode is not limited to image output. Keep it enabled for all Aspose.Page operations in containers and serverless runtimes because PostScript parsing itself uses AWT.

fontconfig, and fonts only if you need them

fontconfig and font files are separate requirements:

• fontconfig is always required. Aspose.Page instantiates java.awt.Font regardless of document content, so the JVM font subsystem must initialize even when every font is embedded in the input.
• Font files are required only when documents reference system fonts by name. If a named font is unavailable, a substitute can be used and conversion can still succeed, but the output typography may differ from the source.

Aspose.Page embeds Liberation Serif as a fallback. This helps conversion continue when a font is missing, but it also means that missing fonts may appear as changed typography instead of a conversion failure.

If all input documents embed their fonts, an image with fontconfig and no additional font packages can be sufficient. For arbitrary third-party documents, install a practical font set:

RUN apt-get install -y --no-install-recommends fonts-dejavu-core fonts-liberation

Liberation Sans and Liberation Mono are metric-compatible substitutes for Arial and Courier New. To use font files shipped with your application, configure PdfSaveOptions:

PdfSaveOptions options = new PdfSaveOptions(true);
options.setAdditionalFontsFolders(new String[] { "/app/fonts" });

The operating system’s standard font folders are searched in addition to the folders you specify.

To determine what your documents need, convert representative files in an image that has fontconfig but no font packages, inspect the diagnostics, and compare the output with a known-good render. A successful conversion and a non-empty output file do not prove that the intended fonts were used.

Diagnose font substitutions and conversion errors

Load the input with PsDocument and use PdfSaveOptions(true) to make the supressErrors setting explicit. Recoverable conversion errors are collected in getExceptions():

PsDocument document = new PsDocument("input.ps");
PdfSaveOptions options = new PdfSaveOptions(true);

document.saveAsPdf("output.pdf", options);

for (Exception ex : options.getExceptions()) {
    System.out.println("Conversion notice: " + ex.getMessage());
}

The API spells setSupressErrors(boolean) and isSupressErrors() with one p. Do not skip the exception loop in an unattended pipeline; record every recoverable conversion problem.

During local diagnosis, enable debug output:

options.setDebug(true);

Debug messages are written to standard output and are useful during deployment validation. The API reference does not identify a dedicated font-substitution event, so enable both error collection and debug output while testing a document that references an unavailable font. Preserve the channel that reports the condition in your deployment, and visually compare the resulting PDF with a known-good render.

Alpine and distroless images

Alpine images need fontconfig and, when documents reference system fonts, an appropriate package such as ttf-dejavu. Distroless images have no package manager, so copy the font configuration and any required font files from a build stage. Validate the JVM font subsystem and representative documents in the exact runtime image you deploy.

AWS Lambda

Aspose.Page is deployed with the Java application, so the function does not require a native converter layer. The following handler assumes that application-specific methods download the input to Lambda’s writable /tmp directory and upload the result. It creates an Aspose.Page License once when the class is initialized:

import com.aspose.eps.PsDocument;
import com.aspose.eps.device.PdfSaveOptions;
import com.aspose.page.License;

public class ConvertHandler implements RequestHandler<S3Event, String> {

    static {
        try {
            new License().setLicense("Aspose.Page.Java.lic");
        } catch (Exception e) {
            throw new RuntimeException("License failed", e);
        }
    }

    @Override
    public String handleRequest(S3Event event, Context context) {
        String inputPath = "/tmp/input.ps";
        String outputPath = "/tmp/output.pdf";

        downloadFromS3(event, inputPath);

        PsDocument document = new PsDocument(inputPath);
        PdfSaveOptions options = new PdfSaveOptions(true);
        options.setAdditionalFontsFolders(new String[] { "/var/task/fonts" });

        document.saveAsPdf(outputPath, options);

        for (Exception ex : options.getExceptions()) {
            context.getLogger().log("Conversion notice: " + ex.getMessage());
        }

        uploadToS3(outputPath);
        return "ok";
    }
}

Set JAVA_TOOL_OPTIONS=-Djava.awt.headless=true as a Lambda environment variable. Ship required fonts in the deployment package under /var/task and reference them explicitly, or use a container image whose font packages you control. Lambda assigns CPU in proportion to memory, so test memory settings with representative documents. Applying the license in a static block avoids repeating that work for every invocation handled by the same execution environment.

Kubernetes and Spring Boot

The application JAR carries Aspose.Page, so the container can use the same probes and resource limits as the rest of the service. Set headless mode and choose a memory limit based on representative documents:

env:
  - name: JAVA_TOOL_OPTIONS
    value: "-Djava.awt.headless=true"
resources:
  limits:
    memory: "1Gi"

Conversion is CPU-bound, and memory use scales with page complexity. Put conversion behind a bounded executor or a queue instead of allowing large documents to compete without limit with HTTP request handling.

Licensing

Review the deployment and distribution terms in Licensing.

Checklist for containerized conversion

• Set -Djava.awt.headless=true as a JVM flag or through JAVA_TOOL_OPTIONS, not in code.
• Install fontconfig unconditionally, including for documents with embedded fonts.
• Determine whether input documents embed fonts or reference them by name, and install font files when required.
• Enable supressErrors and log every entry returned by options.getExceptions().
• Test missing-font behavior with debug output enabled and preserve the diagnostic channel used by the deployed library.
• Use a writable temporary path such as /tmp on Lambda.
• Apply the license once at startup or class initialization, not once per request.
• Test the memory limit with the largest representative document.
• Visually compare output with a known-good render instead of checking only for a non-empty file.

Font substitution can produce a valid PDF whose typography differs from the source, so visual validation is an essential deployment check.