Using Headless Chromium for Server PDFs and Screenshots

This article explains the concept of Headless Chromium, a version of the open-source Chromium web browser that operates without a graphical user interface. It details how developers deploy and control this tool on servers lacking physical monitors to automate web page rendering, specifically focusing on the mechanisms used to capture website screenshots and generate dynamic PDF documents.

What is Headless Chromium?

Headless Chromium is the standard Chromium web browser configured to run without a visible user interface (GUI). While a traditional browser renders web pages onto a physical screen for a human to view and interact with, a headless browser runs entirely in the background.

Despite having no visible window, Headless Chromium uses the exact same rendering engine (Blink) and JavaScript engine (V8) as the standard Google Chrome browser. It downloads HTML, applies CSS styles, executes complex JavaScript, and builds the Document Object Model (DOM) entirely in the system's memory.

Operating on Servers Without Monitors

Production servers, such as cloud virtual machines running Linux, do not have physical monitors attached and rarely have graphical desktop environments installed. They are managed strictly through a Command Line Interface (CLI) to save system resources like RAM and CPU.

Standard browsers crash if launched on these servers because they look for a display output that does not exist. Headless Chromium bypasses this hardware requirement. By passing a specific flag (--headless) when launching the application, the browser is instructed to use a virtual display buffer in memory rather than looking for a physical monitor.

Developers interact with Headless Chromium on a server in two primary ways:

  1. Command Line Interface (CLI): Passing direct terminal commands to the Chromium executable for simple, one-off tasks.
  2. Automation Libraries: Using Node.js libraries like Puppeteer or Playwright, which communicate with the browser via the Chrome DevTools Protocol (CDP). This allows for complex programmatic control, such as logging into a website, clicking buttons, and waiting for data to load before taking an action.

Capturing Website Screenshots

To capture a screenshot on a server, Headless Chromium loads the target URL into memory, executes the page's code, defines a virtual viewport size (e.g., 1920x1080 pixels), and writes the visual representation of that viewport directly to an image file (usually PNG or JPEG).

Using the Command Line: For a quick capture without writing code, a server administrator can run the following command in the terminal:

chromium-browser --headless --screenshot="output.png" --window-size=1920,1080 https://example.com

Using Automation (Puppeteer): For dynamic websites where you must wait for JavaScript elements to load, a script is used. The script instructs Headless Chromium to navigate to the page, wait until network activity ceases, and then capture either the visible viewport or the entire scrollable height of the page. This is widely used for automated visual regression testing and generating social media preview cards.

Generating PDFs

Generating PDFs on a server traditionally required complex backend libraries that tried to convert HTML to PDF, often failing to support modern CSS (like Flexbox or Grid) and ignoring JavaScript entirely. Headless Chromium solves this by utilizing Chrome's native "Print to PDF" engine. Because it is a real browser, the resulting PDF looks identical to what a user would see if they printed the webpage themselves.

The process works by rendering the webpage in memory, applying any specific @media print CSS rules defined by the website, paginating the content, and exporting the result as a .pdf file.

Using the Command Line: You can generate a PDF directly from the server terminal using this command:

chromium-browser --headless --print-to-pdf="document.pdf" https://example.com

Using Automation: In a production environment, businesses use automation scripts to generate invoices, reports, and tickets. A backend server populates an HTML template with user data, opens that HTML file in Headless Chromium, and triggers the PDF generation function. Through code, developers can precisely control page margins, paper format (such as A4 or Letter), background graphics rendering, and custom headers and footers.