DDEV and Gotenberg: using custom fonts for your PDFs

Gotenberg is an excellent tool for generating PDFs from HTML/CSS. With DDEV, the ddev-gotenberg extension makes it easy to integrate into your development environment. But as soon as you want to use custom fonts, things get complicated: Gotenberg only knows the system fonts installed in its container.

I encountered this problem on an e-commerce project where PDFs (invoices, delivery notes) had to follow the client’s brand guidelines with a specific font. Here’s how I solved it properly.

The problem

By default, Gotenberg uses a Docker image with a limited set of fonts. If your CSS references a font that isn’t installed in the container, it will simply be ignored and replaced by a fallback font.

The solution: create a custom Docker image

The idea is to create a Docker image based on Gotenberg, in which we add our fonts.

1. Create the Dockerfile

In your project, create a gotenberg.Dockerfile file:

FROM gotenberg/gotenberg:8
USER root
COPY ./fonts/ /usr/local/share/fonts/
RUN fc-cache -f -v
USER gotenberg

The fc-cache -f -v forces the font cache to rebuild, which avoids detection issues.

2. Prepare the fonts

Create a fonts/ folder at the same level as your Dockerfile and place your .ttf or .otf files there.

3. Build the image

docker build -t gotenberg_custom -f gotenberg.Dockerfile .

4. Configure DDEV to use this image

Rather than modifying the docker-compose file generated by the addon (which would be overwritten on the next ddev restart), use an environment variable:

ddev dotenv set .ddev/.env.gotenberg --gotenberg-docker-image=gotenberg_custom

This command creates a .ddev/.env.gotenberg file with the following content:

GOTENBERG_DOCKER_IMAGE="gotenberg_custom"

5. Restart DDEV

ddev restart

The font is now available and can be used directly in your CSS stylesheets:

body {
    font-family: 'MyCustomFont', sans-serif;
}

Conclusion

This approach keeps your configuration clean and maintainable. The custom image can be versioned and shared with your team, and the DDEV configuration remains intact when the addon is updated.

If you have other tips about Gotenberg or DDEV, feel free to share them in the comments.