Document generation moves to Linux the moment it goes into a container, a Kubernetes job or a
function. The code does not change. The image does — and the thing that catches everybody is
fonts.
The .NET runtime images ship without fonts. Nothing in the assembly step fails when they are
missing: the document is produced, text is laid out with whatever substitute can be found, and the
result is wrong in ways nobody sees until a reader opens it — a line break in a new place, a table
that overflows, one page that became two.
fontconfig is what makes fonts discoverable at all.
fonts-liberation provides metric-compatible substitutes for Arial, Times New Roman and
Courier New, which is what most templates ask for.
A template that uses other fonts needs those fonts in the image too: copy them into
/usr/share/fonts and run fc-cache -f.
Prove it, do not assume it
A DOCX hides a font problem. Rendering does not — which is what makes
GeneratePreview a good smoke test for an image.
Note
DocumentAssembler.GeneratePreview is available since version 26.11.
PreviewOptionspreviewOptions=newPreviewOptions(pageNumber=>File.Create(Path.Combine(outputDirectory,$"page{pageNumber}.png")),(pageNumber,pageStream)=>pageStream.Dispose());previewOptions.PreviewFormat=PreviewFormats.PNG;previewOptions.Resolution=120;// dots per inch, 96 by defaultnewDocumentAssembler().GeneratePreview(documentPath,previewOptions);
Render one page in the build of the image and compare it with a reference. A missing font becomes a
failing build instead of a support ticket.
The same image is the base of an Azure Functions custom handler, an AWS Lambda container image or a
Cloud Run job. Three things to plan for:
Cold start. The first assembly in a process pays for loading the engine. Keep an instance
warm if the first request is user-facing, or accept that it is slower.
Writable space. Assemble to streams. A function’s file system is small, temporary and
sometimes read-only; nothing in document assembly requires a file.
The licence. Ship it as a secret rather than inside the image, and apply it once per
process, not per invocation.
Memory and throughput
A document is assembled in memory, so the working set follows the size of the data and of the
output rather than the number of templates. Two habits keep a batch predictable:
assemble to a stream and dispose it, rather than keeping the result around;
process in batches, and let the process exit between them in a job — a container that runs one
batch and stops cannot leak.
Licensing
Apply the licence once at start-up. The path can come from an environment variable so the image
stays free of it:
Why does a document generated in a container look different?
The .NET runtime images ship with no fonts. Text is laid out with a substitute, so line breaks,
column widths and page counts move. Nothing throws.
Which packages have to be installed in the image?fontconfig, which makes fonts discoverable at all, and a font package such as
fonts-liberation, which is metric-compatible with Arial, Times New Roman and Courier New.
How do you add a corporate font?
Copy it into /usr/share/fonts and run fc-cache -f.
How do you prove the fonts are present?
Render a page with DocumentAssembler.GeneratePreview during the image build and compare it with a
reference image. A DOCX hides the problem because layout is decided by whatever opens it.
Does this run in Azure Functions or AWS Lambda?
Yes, on the same base image. Assemble to streams, apply the licence once per process rather than
per invocation, and keep an instance warm if the first request is user-facing.