If a document generated in a container looks wrong, it is almost always the fonts: the .NET
runtime images ship with none. Install fontconfig and fonts-liberation, and render a page
with GeneratePreview in the build to prove they are there.
Document generation moves to Linux the first time it goes into a container, a Kubernetes job or a
function. The C# does not change — the same AssembleDocument call, the same templates. The image
does, and the thing that catches almost everybody is fonts.
The sample for this post is on GitHub — document-generation-docker-net.
Why do documents look wrong in a container?
The .NET runtime images ship without fonts. Not a reduced set — none.
Nothing throws. The document is produced, text is laid out with whatever substitute can be found, and the result is wrong in the quiet ways: a line break in a new place, a table that spills past its column, a report that was one page and is now two with a lonely signature block on the second.
Nobody notices in CI, because CI checks that a file was produced. Somebody notices three weeks later, in a customer’s inbox.
How do you install fonts for document generation on Linux?
RUN apt-get update \
&& apt-get install -y --no-install-recommends fontconfig fonts-liberation \
&& rm -rf /var/lib/apt/lists/*
fontconfigis what makes fonts discoverable at all. Without it, installing fonts does nothing.fonts-liberationprovides metric-compatible substitutes for Arial, Times New Roman and Courier New — which is what most templates ask for. Metric-compatible is the important word: the glyphs differ slightly, the widths do not, so the layout holds.
A template that uses a corporate font needs that font in the image as well: copy it into
/usr/share/fonts and run fc-cache -f.
How do you prove the fonts are really there?
A DOCX hides the problem — the layout is decided when something opens it. Rendering does not,
which is what makes GeneratePreview the right smoke test for an image.
New in 26.11 —
DocumentAssembler.GeneratePreviewis a new API in GroupDocs.Assembly for .NET.
PreviewOptions previewOptions = new PreviewOptions(
pageNumber => File.Create($"page{pageNumber}.png"),
(pageNumber, pageStream) => pageStream.Dispose());
previewOptions.PreviewFormat = PreviewFormats.PNG;
previewOptions.Resolution = 120; // dots per inch, 96 by default
new DocumentAssembler().GeneratePreview("report.docx", previewOptions);
Render one page in the build of your image and compare it against a reference PNG. A font that went missing when somebody slimmed the base image becomes a red build instead of a support ticket.
The sample also has a fonts command, which is the fastest way to answer is it the fonts?:
docker run --rm document-generation-dotnet fonts
/usr/share/fonts: 0 font file(s)
total: 0 font file(s)
No fonts found. Text will be laid out with a substitute and the report
will not match what you see on a desktop.
The whole Dockerfile
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY . .
RUN dotnet publish src/DockerReports/DockerReports.csproj -c Release -o /app
FROM mcr.microsoft.com/dotnet/runtime:8.0
WORKDIR /work
RUN apt-get update \
&& apt-get install -y --no-install-recommends fontconfig fonts-liberation \
&& rm -rf /var/lib/apt/lists/*
COPY --from=build /app /app
COPY templates /work/templates
COPY data /work/data
ENTRYPOINT ["dotnet", "/app/report.dll"]
CMD ["report"]
What changes in Azure Functions, AWS Lambda and Cloud Run?
The image above is also the base of an Azure Functions custom handler, an AWS Lambda container image or a Cloud Run job.
- Cold start. The first assembly in a process pays for loading the engine. If the first request is user-facing, keep an instance warm.
- Writable space. Assemble to streams. A function’s file system is small, temporary and sometimes read-only — and document assembly never requires a file.
- The licence is a secret, not an image layer. Mount it and apply it once per process, not per invocation.
Questions people ask
Why does my generated document look different in Docker than on my machine? The .NET runtime images ship with no fonts. Text is laid out with whatever substitute can be found, so line breaks, table widths and page counts move. Nothing throws.
Which font package should I install?
fontconfig plus fonts-liberation. Liberation is metric-compatible with Arial, Times New Roman
and Courier New — the glyphs differ slightly, the widths do not, so the layout holds.
Do I need a corporate font in the image?
Yes, if a template asks for one. Copy it into /usr/share/fonts and run fc-cache -f.
Can I run document generation in Azure Functions or AWS Lambda? Yes, on the same base image. Assemble to streams rather than files, apply the licence once per process, and keep an instance warm if the first request is user-facing.
How do I catch a missing font in CI instead of in a customer’s inbox?
Render a page with DocumentAssembler.GeneratePreview during the image build and compare it with a
reference PNG. A font that disappears when somebody slims the base image becomes a red build.
Try it
git clone https://github.com/groupdocs-assembly/document-generation-docker-net.git
cd document-generation-docker-net
docker build -t document-generation-dotnet .
docker run --rm document-generation-dotnet fonts
Then comment the apt-get block out, rebuild, and render the same page again. The difference is the
whole post.
The reference page is Running in Docker and serverless. If this is going behind a web endpoint, read Generate and download reports in ASP.NET Core next.