Docker Font Configuration for HTML to Image in .NET on Linux

Why Fonts Must Be Installed on Linux for HTML to Image Conversion

Linux systems – especially minimal Docker runtime images – do not include TrueType fonts by default. In many base images, no usable fonts are installed at all. Server-side HTML to Image (PDF, XPS, etc.) conversion in .NET relies entirely on fonts available on the operating system. The rendering engine does not ship with built-in fonts and does not load web fonts as a browser would.

If no fonts are installed in the Linux environment:

CSS font-family declarations cannot be resolved
no fallback fonts are available
text is not rendered in the output image

As a result, the generated image may contain no visible text. To ensure correct rendering, fonts must be explicitly installed on the Linux system or in the Docker image before running the conversion.

Installing Fonts in Docker

In Docker environments, fonts must be installed during the image build process, specifically in the runtime stage that will execute the application. Minimal .NET runtime images do not include usable TrueType fonts, and without them, text will not be rendered.

This section explains how to install fonts and make them available to Aspose.HTML inside a Linux-based Docker container.

Why Fonts Must Be Installed in the Base Image

In multi-stage Dockerfiles, the application runs inside the base runtime stage. If fonts and font configuration utilities are not installed in this stage, they will not be available during conversion.

For reliable rendering, the base runtime image must include:

system TrueType/OpenType fonts;
fontconfig, responsible for font discovery, matching, and cache management;
UTF-8 locale configuration required for correct Unicode text processing.

Installing System Fonts and Font Discovery Tools

The following Dockerfile fragment installs a basic set of TrueType fonts together with fontconfig, which is responsible for font discovery, matching, and caching on Linux. You can view the full Dockerfile by following the link.

 1FROM mcr.microsoft.com/dotnet/runtime:6.0 AS base
 2
 3RUN apt-get update && apt-get install -y --no-install-recommends \
 4        fontconfig \
 5        fonts-dejavu-core \
 6        fonts-dejavu-extra \
 7        fonts-liberation \
 8        fonts-freefont-ttf \
 9        locales \
10        ca-certificates \
11    && rm -rf /var/lib/apt/lists/*

This configuration provides:

fontconfig – Enables the system to locate and match fonts during rendering;
fonts-dejavu-*, fonts-liberation, fonts-freefont-ttf – Install standard TrueType fonts required for text rendering;
ca-certificates – Required when converting HTML content loaded from HTTPS sources.

After installation, system fonts are placed in the standard Linux directory: /usr/share/fonts.

This directory becomes the default font source for the rendering engine. If no custom font folders are configured in code, Aspose.HTML automatically uses fonts available in /usr/share/fonts.

In other words:

Fonts installed via apt-get become system fonts.
These fonts are used by default during conversion.
No additional configuration is required in C# if system fonts are sufficient.

Without installing fonts, the renderer cannot resolve CSS font-family declarations, and text may not appear in the generated image or PDF.

Configuring UTF-8 Locale

Text rendering on Linux also depends on proper locale configuration. The following setup enables UTF-8 support:

1RUN sed -i 's/# \(en_US.UTF-8 UTF-8\)/\1/' /etc/locale.gen \
2    && locale-gen
3
4ENV LANG=en_US.UTF-8 \
5    LANGUAGE=en_US:en \
6    LC_ALL=en_US.UTF-8 \
7    DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=false

This ensures:

correct processing of Unicode characters
stable text rendering across environments

Rebuilding the Font Cache

After installing fonts, rebuild the font cache:

1RUN fc-cache -f -v

This step ensures that newly installed fonts are immediately discoverable by the rendering engine and helps avoid font detection issues inside containers.

Key Takeaway

When fonts are installed in a Linux Docker image, they are placed in the standard system directory: /usr/share/fonts. This directory becomes the default font source for HTML to Image (PDF, XPS, etc.) conversion. If no custom font folder is configured in code, Aspose.HTML automatically uses fonts from /usr/share/fonts.

To ensure reliable rendering in Docker:

Install required TrueType fonts into the image.
Ensure they are available under /usr/share/fonts.
Configure UTF-8 locale.
Rebuild the font cache using fc-cache.

If no fonts are installed in the container, text will not be rendered. If a custom font folder is later configured in code, system fonts from /usr/share/fonts will no longer be used automatically.

Usage Examples: HTML to Image Conversion in .NET

Basic Conversion Example

 1using Aspose.Html;
 2using Aspose.Html.Converters;
 3using Aspose.Html.Saving;
 4using System.IO;
 5
 6// Uses system fonts from /usr/share/fonts by default
 7
 8// Create an instance of the Configuration class
 9var configuration = new Configuration();
10
11// Define input and output
12string inputHtml = "/data/input.html";        // local file path or URL
13string outputImage = "/data/output.png";      // output PNG path
14
15// Load HTML document
16using var document = new HTMLDocument(inputHtml, configuration);
17
18// Convert HTML to PNG
19Converter.ConvertHTML(document, new ImageSaveOptions(), outputImage);

Using Custom Fonts

If your HTML uses custom fonts (for example, corporate or branded fonts), you can register a specific font folder in code:

 1using Aspose.Html;
 2using Aspose.Html.Converters;
 3using Aspose.Html.Saving;
 4using Aspose.Html.Services;
 5using System.IO;
 6
 7// Create Aspose.HTML configuration
 8var configuration = new Configuration();
 9
10// Register additional font folders
11var uac = configuration.GetService<IUserAgentService>();
12uac.FontsSettings.SetFontsLookupFolder("/usr/local/customfontfolder", true);
13
14// Define input and output
15string inputHtml = "/data/input.html";        // local file path or URL
16string outputImage = "/data/output.png";      // output PNG path
17
18// Load HTML document
19using var document = new HTMLDocument(inputHtml, configuration);
20
21// Convert HTML to PNG
22Converter.ConvertHTML(document, new ImageSaveOptions(), outputImage);

Important Behavior

When SetFontsLookupFolder is used:

The specified custom folder /usr/local/customfontfolder becomes the exclusive font source.
System fonts located in /usr/share/fonts are no longer used automatically.
Only fonts available in the configured custom folder are considered during rendering.

This means:

If the custom folder /usr/local/customfontfolder contains valid .ttf or .otf files, they will be used.
If the custom folder is empty or missing required fonts, text will not be rendered.
System-installed fonts from /usr/share/fonts will not act as a fallback.

For this reason, when using a custom font directory, ensure that all required fonts are copied into the folder, the folder is mounted or included in the Docker image, and font cache is rebuilt if fonts are installed at build time.

Font Resolution Flow on Linux

Font resolution during HTML to Image conversion follows a strict rule:

If SetFontsLookupFolder is NOT used → Fonts are loaded from the system directory /usr/share/fonts.
If SetFontsLookupFolder IS used → Only fonts from the specified custom folder are used.

There is no automatic fallback between system and custom font sources. Once a custom lookup folder is configured, it becomes the exclusive font source.

Summary

Docker containers do not include fonts by default.
Fonts must be installed in the base runtime stage to /usr/share/fonts.
fontconfig and a UTF-8 locale are required.
Font cache should be rebuilt after installation.
Custom fonts must be explicitly registered or installed.
When using SetFontsLookupFolder, system fonts in /usr/share/fonts are not used automatically.

Without these steps, accurate HTML to Image rendering on Linux is not possible.

Help & Support

If you need help or have questions about running Aspose.HTML in docker, please contact Free Support Forum or Free Consulting. We will be happy to help!

Convert HTML to TIFF Convert HTML to GIF

Analyzing your prompt, please hold on...

An error occurred while retrieving the results. Please refresh the page and try again.