Chrome headless modes with Java SDK

This guide shows how to run the packaged Docker sample for Chrome-backed conversions with Java SDK.

HTML-to-PDF and email-to-PDF conversions on Linux rely on Chrome for rendering. This also applies to conversions of EML and MSG files, because email bodies can contain HTML that must be rendered faithfully before PDF export.

When you need this setup

Use this sample when you want to run Chrome-backed conversions inside Docker on Linux, including:

• HTML to PDF
• EML to PDF
• MSG to PDF
• Any other conversion path that renders HTML through Chrome on Linux

Why Docker setup matters

A basic Linux container often fails for one of these reasons:

• Chrome isn’t installed.
• The image doesn’t include the packages required by Chrome.
• The container runs as root, which causes Chrome’s sandboxed process launch to fail.
• Docker’s default seccomp profile may block the user-namespace sandbox Chrome expects.

We don’t recommend disabling Chrome’s sandbox with --no-sandbox unless you fully understand the security trade-offs.

Run the packaged sample with Docker

Docker is the primary and recommended way to run this packaged sample.

After downloading and extracting the sample package, open a terminal in the sample folder and use the Docker commands shown below in the language-specific section of this guide.

What the packaged sample already includes

The packaged sample folder already contains the Docker assets required to run the sample:

• Dockerfile
• docker-compose.yml
• chrome-seccomp.json

These files are preconfigured for the sample. You don’t need to create Docker files manually.

How the packaged Docker setup works

The included Docker assets already handle the required container behavior:

• Install Chrome headless shell and its Linux dependencies
• Run the sample as a non-root user
• Apply the included chrome-seccomp.json profile
• Mount the sample folder so output.pdf is written back to your local package directory

Included seccomp profile

The packaged sample includes chrome-seccomp.json next to the Docker files, so you can inspect or customize it locally if needed.

Run this packaged Java sample with Docker

From the packaged sample folder, run:

docker run --rm \
  --platform linux/amd64 \
  --security-opt seccomp=chrome-seccomp.json \
  -w /app \
  -v "$PWD:/app" \
  -e HOME=/home/appuser \
  "$(docker build -q --platform linux/amd64 -f Dockerfile .)" \
  /bin/sh -c 'chmod -R o+rwX /app && exec runuser -u appuser -- mvn compile exec:exec'

Run this packaged Java sample with Docker Compose

From the packaged sample folder, run:

docker compose -f docker-compose.yml run --build --rm appuser

If the run succeeds, the package writes output.pdf to the sample folder.

You can also download this packaged sample and run it directly.

What this packaged Java sample does

The packaged Java sample loads the included input.html file and writes the converted result to output.pdf.

Email conversion workflows such as MSG and EML to PDF also rely on Chrome-backed rendering in Docker.

The SDK code executed by the packaged sample is:

package io.nutrient.Sample;

import io.nutrient.sdk.Document;
import io.nutrient.sdk.exceptions.NutrientException;

public class HeadlessModesGoogleChrome {
    public static void main(String[] args) throws NutrientException {
        try (Document document = Document.open("input.html")) {
            document.exportAsPdf("output.pdf");
        }
    }
}

Troubleshooting checklist

If conversion still fails in Docker, verify the following:

• chrome-headless-shell starts inside the container.
• The process runs as a non-root user.
• HOME points to a writable directory for that user.
• Your mounted working directory is writable by the unprivileged user.
• You’re using a seccomp profile that enables Chrome’s sandbox on Docker.
• chrome-headless-shell is on PATH inside the container or explicitly configured in the SDK.
• You didn’t accidentally force Chrome to run with an invalid or missing browser path.

Related guides

• Java SDK guides