Running Markdown to PDF Converters inside Docker Containers

When developing modern web apps, the “it works on my machine” problem frequently occurs with document generation tools. PDF rendering engines often depend on local system fonts, rendering libraries, and headless web browsers. By configuring a markdown to pdf docker container, you package all dependencies into a single, predictable environment that behaves identically in local development, staging, and production.

In this guide, we will build a Docker container configured to run a Puppeteer-based Markdown to PDF converter, addressing the typical hurdles of installing headless Chrome in Linux containers.

Why Containerize Document Converters?

Moving your PDF generation process into a Docker container offers several concrete advantages:

• Consistent Fonts: Ensures system fonts (like Arial or Times New Roman) render exactly the same way without depending on host OS setups.
• Isolate Browser Complexities: Headless browsers require numerous native Linux libraries (like libxss1 or libasound2). Docker keeps these out of your main host OS.
• Easy Deployments: Deploy your document engine as a microservice on Amazon ECS, Kubernetes, or Google Cloud Run with zero environmental setup.

Writing the Dockerfile

Puppeteer is a popular choice for Markdown to PDF conversion because it prints CSS styling accurately. However, running Chromium inside a Linux container requires installing specific dependencies and launching it with sandbox safety flags disabled.

Here is a production-ready Dockerfile that sets up Chromium and Node.js for Markdown conversions:

# Use a lightweight Node LTS image as the base
FROM node:20-slim

# Install system dependencies required for Headless Chrome
RUN apt-get update && apt-get install -y \
    wget \
    gnupg \
    ca-certificates \
    procps \
    libxss1 \
    libasound2 \
    libatk1.0-0 \
    libatk-bridge2.0-0 \
    libc6 \
    libcairo2 \
    libcups2 \
    libdbus-1-3 \
    libexpat1 \
    libfontconfig1 \
    libgbm1 \
    libgcc1 \
    libgconf-2-4 \
    libgdk-pixbuf2.0-0 \
    libglib2.0-0 \
    libgtk-3-0 \
    libnspr4 \
    libpango-1.0-0 \
    libpangocairo-1.0-0 \
    libstdc++6 \
    libx11-6 \
    libx11-xcb1 \
    libxcb1 \
    libxcomposite1 \
    libxcursor1 \
    libxdamage1 \
    libxext6 \
    libxfixes3 \
    libxi6 \
    libxrandr2 \
    libxrender1 \
    libxtst6 \
    fonts-liberation \
    --no-install-recommends \
    && rm -rf /var/lib/apt/lists/*

# Set working directory
WORKDIR /usr/src/app

# Copy package descriptors and install packages
COPY package*.json ./
RUN npm install

# Copy application script files
COPY . .

# Run the app as a non-privileged user for security
USER node

# Default command to run
CMD ["node", "index.js"]

Running the Container Locally

Once you have built your Dockerfile, you can run conversions by mounting a local directory into your container.

First, build your Docker image:

docker build -t markdown-pdf-generator .

Then, run the container and mount your current working directory so that the script can access and read your Markdown files and output the compiled PDFs:

docker run --rm \
  -v "$(pwd):/usr/src/app/data" \
  markdown-pdf-generator \
  node index.js /usr/src/app/data/document.md /usr/src/app/data/output.pdf

Best Practices for Docker PDF Services

To ensure fast rendering, consider running your conversion script as a long-lived HTTP microservice rather than spinning up a new container for every single document request. Initializing a new Chromium instance inside Docker on every run adds roughly 1-2 seconds of startup overhead, whereas a running web service can perform the conversion in milliseconds.

Additionally, make sure you configure Chromium to run with the --no-sandbox flag inside Docker since the default user permissions of Docker environments can prevent sandbox initialization.

Conclusion

Packaging your Markdown to PDF converters inside a Docker environment is the best way to avoid rendering surprises in production. It guarantees your fonts, spacing, and layouts behave exactly the same way everywhere. If you want to convert documents immediately without managing Docker images or server environments, you can always use our free online editor for instant exports.