Solving Missing Font Issues in .NET Docker Containers

TLDR

• Root Cause: Official .NET Docker images (e.g., Debian-based) do not install font packages by default to minimize image size, resulting in a missing /usr/share/fonts directory.
• Solution: Install ttf-mscorefonts-installer and fontconfig in the Dockerfile, then run fc-cache to update the font cache.
• Version Differences: Debian 11 (.NET 6) uses /etc/apt/sources.list to configure sources, while Debian 12 (.NET 8) uses /etc/apt/sources.list.d/debian.sources.

---

Missing Fonts in Docker Containers

When this issue occurs: When an application requires image processing (such as generating reports or drawing) or relies on specific fonts for rendering, using the default .NET Dockerfile generated by Visual Studio will result in a missing /usr/share/fonts directory inside the container, causing font loading to fail.

This is because the mcr.microsoft.com/dotnet/aspnet image uses a slimmed-down Linux distribution that does not come with pre-installed font packages. For .NET 6 (Debian 11) environments, you can add fonts in your Dockerfile using the following method:

FROM mcr.microsoft.com/dotnet/aspnet:6.0 AS base

# Enable contrib sources and install font packages
RUN sed -i'.bak' 's/$/ contrib/' /etc/apt/sources.list
RUN apt-get update; apt-get install -y ttf-mscorefonts-installer fontconfig

# Force refresh the font cache
RUN fc-cache -f -v

WORKDIR /app
# ... Subsequent build steps

---

Handling Environment Differences in .NET 8 Dockerfiles

When this issue occurs: When upgrading to .NET 8 (Debian 12), applying the sed command used for Debian 11 directly will cause the build to fail (Exit code 21) because the /etc/apt/sources.list file no longer exists.

Debian 12 has changed the package source configuration to /etc/apt/sources.list.d/debian.sources. The fix for .NET 8 is as follows:

FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base

# Modify source configuration for Debian 12
RUN sed -i 's/^Components: main$/& contrib/' /etc/apt/sources.list.d/debian.sources

# Install font packages
RUN apt-get update; apt-get install -y ttf-mscorefonts-installer fontconfig

# Refresh the font cache
RUN fc-cache -f -v

USER app
WORKDIR /app
# ... Subsequent build steps

WARNING

When installing ttf-mscorefonts-installer, ensure that your environment allows for automated installation and confirm that the relevant license terms comply with your project requirements.

---

Changelog

1. 2024-08-09

   • Initial documentation created.