How to Run IronPDF for Java in Google Cloud

Why Don't Default Cloud Function Images Work?

Default Google Cloud Function runtime images are minimal by design — they include only the packages needed to execute function code written in common languages. IronPDF's Chromium-based rendering engine depends on a broader set of Linux system libraries (fonts, graphics libraries, sandboxing tools) that are absent from the standard images.

Google publishes a full list of available system packages for each runtime at the Google Cloud Functions system packages reference. Chromium's dependencies are not included in any of the standard 2nd-gen runtimes. Attempting to load the IronPDF engine in the default image results in a native library load failure at startup.

The solution is to build a custom Docker image that explicitly installs those packages before the function binary is added. This approach is fully supported by Google Cloud Functions and is the same strategy recommended for any function that requires native binaries. Refer to the IronPDF Linux deployment guide for the complete list of packages to include.

How Do I Build a Custom Dockerfile for Google Cloud?

A custom Dockerfile gives complete control over the runtime environment. Start from the official Google Cloud Functions Java base image, then install the system libraries that Chromium requires.

The Dockerfile below demonstrates the recommended pattern. Replace the COPY and CMD entries with the specifics of your function project:

//:path=Dockerfile
# Use the official Google Cloud Functions Java 17 base image
FROM gcr.io/google-appengine/java17:latest

# Install Chrome system dependencies required by IronPDF's rendering engine
RUN apt-get update && apt-get install -y \
    libglib2.0-0 \
    libnss3 \
    libatk1.0-0 \
    libatk-bridge2.0-0 \
    libcups2 \
    libdrm2 \
    libxkbcommon0 \
    libxcomposite1 \
    libxdamage1 \
    libxfixes3 \
    libxrandr2 \
    libgbm1 \
    libasound2 \
    libpango-1.0-0 \
    libpangocairo-1.0-0 \
    --no-install-recommends \
    && rm -rf /var/lib/apt/lists/*

# Grant execute permissions on /tmp so the IronPDF engine can extract there
RUN chmod 777 /tmp/

# Copy the compiled JAR and set the entry point
COPY target/your-function.jar /app/function.jar
CMD ["java", "-jar", "/app/function.jar"]

The chmod 777 /tmp/ line is necessary because IronPDF needs to write and execute the engine binary during initialization. Without execute permission on the working directory, the engine will fail to start.

How Do I Configure pom.xml for Google Cloud Deployment?

The standard ironpdf Maven artifact bundles engine binaries for multiple platforms. For Google Cloud Functions (which run on Linux x86-64), add the platform-specific engine artifact to keep the deployment image lean and to ensure the correct binary is always available:

//:path=pom.xml
<dependencies>

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

//:path=pom.xml
<dependencies>

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

Always update the version number to the latest IronPDF for Java release. The ironpdf-engine-linux-x64 artifact must match the version of the core ironpdf artifact exactly.

How Do I Add the Maven Shade Plugin?

When deploying to Google Cloud Functions as an uber-JAR (fat JAR), the maven-shade-plugin ensures that service loader files from all transitive dependencies are merged correctly. Without it, some gRPC service registrations can be silently dropped, causing the engine to fail to initialize.

Add the following plugin configuration to the <build><plugins> section of your pom.xml:

//:path=pom.xml
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-shade-plugin</artifactId>
    <version>3.2.4</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>shade</goal>
            </goals>

            <configuration>
                <transformers>
                    <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
                </transformers>
            </configuration>
        </execution>
    </executions>
</plugin>

//:path=pom.xml
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-shade-plugin</artifactId>
    <version>3.2.4</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>shade</goal>
            </goals>

            <configuration>
                <transformers>
                    <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
                </transformers>
            </configuration>
        </execution>
    </executions>
</plugin>

The ServicesResourceTransformer is the critical piece. It combines META-INF/services/ entries from every dependency JAR into a single merged file. gRPC uses Java's ServiceLoader mechanism, so merged service files are required for transport selection (HTTP/2 vs. plain text) to work at runtime.

How Do I Add Optional gRPC Dependencies?

In some deployment configurations — particularly when using a shaded JAR with certain versions of the Google Cloud Functions framework — explicit gRPC transport dependencies are needed. Add these if the function fails to start with a gRPC transport or channel error:

//:path=pom.xml
<dependencies>

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

//:path=pom.xml
<dependencies>

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

In most cases, including grpc-netty-shaded is sufficient for production. The grpc-okhttp transport is a lighter alternative useful when minimizing image size is a priority. Add perfmark-api only if you encounter classpath warnings about missing tracing annotations.

How Do I Set Resource Limits for Google Cloud Functions?

IronPDF starts a Chromium subprocess inside the Cloud Function container during its first invocation. Chromium's startup and initial rendering are memory-intensive, and the function must remain alive long enough for the engine to initialize. The default resource limits for Cloud Functions are too low for reliable operation.

Configure the following limits in the Google Cloud Console or via the gcloud CLI when deploying the function:

These values are starting points. High-volume or complex PDF generation may require higher memory allocations. Monitor Cloud Function memory usage metrics in the Google Cloud Console and increase limits if you observe out-of-memory errors.

How Do I Configure the Working Directory and File Permissions?

The IronPDF engine extracts its binary to a working directory at startup. On Google Cloud Functions, the only writable and executable path is /tmp/. Set the working directory explicitly before calling any IronPDF API, and ensure the Dockerfile grants the necessary permissions on that path.

Add this configuration call at the top of your function entry point, before any PDF operations:

//:path=/static-assets/pdf/content-code-examples/tutorials/google-cloud/configure-working-directory.java
import com.ironsoftware.ironpdf.Settings;
import java.nio.file.Paths;

public class PdfFunction {
    static {
        // Must be called before any IronPDF operation.
        // /tmp/ is the only writable and executable directory in Cloud Functions.
        Settings.setIronPdfEngineWorkingDirectory(Paths.get("/tmp/"));
    }
}

//:path=/static-assets/pdf/content-code-examples/tutorials/google-cloud/configure-working-directory.java
import com.ironsoftware.ironpdf.Settings;
import java.nio.file.Paths;

public class PdfFunction {
    static {
        // Must be called before any IronPDF operation.
        // /tmp/ is the only writable and executable directory in Cloud Functions.
        Settings.setIronPdfEngineWorkingDirectory(Paths.get("/tmp/"));
    }
}

Then add the corresponding permission command to your Dockerfile:

//:path=Dockerfile
# Ensure the IronPDF engine can extract and run binaries from /tmp/
RUN chmod 777 /tmp/

Using a static {} initializer block guarantees the working directory is configured before any class in your function attempts to load the IronPDF engine. If you set it in an instance method or request handler, there is a risk that another thread initializes the engine before the path is configured.

What Are the Next Steps?

This guide covers the complete configuration for running IronPDF for Java inside a Google Cloud Function using a custom Docker container. The key points are: use a custom Dockerfile that installs Chrome system dependencies, include the ironpdf-engine-linux-x64 Maven artifact, configure the working directory to /tmp/, set the timeout to at least 330 seconds and memory to at least 2,048 MB, and add the maven-shade-plugin to merge service loader files.

To explore more of what IronPDF for Java can do, visit the IronPDF for Java documentation or try one of these guides:

• IronPDF for Java on Linux — Understand the full list of Chrome dependencies for Linux deployments
• IronPDF for Java on AWS Lambda — Similar Docker-based deployment guide for AWS
• HTML to PDF conversion in Java — Core rendering workflow for your function logic

Get a free trial license to test IronPDF for Java in your Google Cloud environment. A license key is required for production deployments. Purchase a license when you are ready to go live.