DPTCloud
Back to articles
Technology Insight

Building a Private PDF Conversion Service for Corporate Offices Using Gotenberg on Docker VPS

June 3, 2026

Introduction: The PDF Dilemma in Modern Enterprise Operations

In the modern corporate ecosystem, the Portable Document Format (PDF) remains the gold standard for exchanging contracts, financial statements, reports, and official memos. However, managing PDF generation at scale presents a persistent challenge for IT infrastructure and development teams. Relying on public, third-party online converters exposes sensitive corporate data to compliance violations, particularly under strict frameworks like GDPR or local data privacy laws. Conversely, licensing commercial enterprise PDF software can introduce exorbitant, seat-based recurring costs.

To balance security, performance, and cost-efficiency, forward-thinking organizations are shifting toward self-hosted infrastructure. This guide provides a comprehensive blueprint for deploying a Private PDF Conversion Service within your corporate network using Gotenberg hosted on a Docker-powered Virtual Private Server (VPS). By the end of this article, your IT team will have total control over your document processing pipeline, ensuring complete data sovereignty and frictionless automation.

---

What is Gotenberg and Why It Beats the Alternatives

Gotenberg is an open-source, stateless API wrapper designed for high-performance document conversion. Written in Go, it coordinates headless instances of powerful engines like Chromium and LibreOffice to transform various file formats into production-grade PDFs. Unlike heavy, monolithic document servers, Gotenberg is purpose-built for containerized environments, making it exceptionally lightweight and developer-friendly.

Key Capabilities of Gotenberg:

  • Web-to-PDF Conversion: Leverages headless Chromium to accurately render complex HTML, CSS, JavaScript, SVG, and WebP assets into pixel-perfect PDF documents.
  • Office Document Processing: Utilizes headless LibreOffice to convert Microsoft Office formats (.docx, .xlsx, .pptx) and OpenDocument formats without layout breaking.
  • PDF Manipulation: Supports merging multiple PDF files, splitting pages, and appending cover sheets seamlessly via simple API calls.
  • Compliance & Archiving: Built-in support for generating PDF/A-1a, PDF/A-2b, and PDF/A-3b formats, which are critical for long-term digital archiving and corporate compliance.
"By consolidating document rendering into a single stateless container, Gotenberg eliminates the need for expensive software licenses and complex local dependencies on application servers."
---

Architectural Advantages of a Private PDF Service

Deploying Gotenberg on a private Docker VPS introduces several structural advantages over public SaaS APIs or local library implementations:

  1. Absolute Data Privacy: Files are processed entirely within your isolated VPS memory space. No external logs are kept, and no documents are uploaded to third-party clouds, effectively neutralizing data leak vectors.
  2. Resource Isolation: PDF conversion, especially office document rendering, is highly CPU and memory-intensive. Running this service inside a dedicated Docker container protects your main application servers from unexpected performance spikes.
  3. Language Agnostic Integration: Because Gotenberg exposes a clean, standardized HTTP REST API, any software in your enterprise toolkit—whether written in Python, Node.js, PHP, Java, or .NET—can communicate with it effortlessly.
---

Step-by-Step Deployment Guide on Docker VPS

To successfully set up your private conversion engine, ensure your destination VPS has a clean Linux installation (Ubuntu 22.04 LTS or 24.04 LTS recommended) with Docker and Docker Compose pre-installed.

Step 1: Setting Up the Directory Structure

First, access your VPS via SSH and establish an organized workspace for your service configuration files:

mkdir -p /opt/pdf-service
cd /opt/pdf-service

Step 2: Crafting the Docker Compose Configuration

Create a file named docker-compose.yml using your preferred text editor. Paste the following optimal multi-container architecture configuration:

version: '3.8'

services:
  gotenberg:
    image: gotenberg/gotenberg:8
    container_name: enterprise-pdf-engine
    restart: always
    environment:
      - CHROMIUM_DISABLE_ROUTES=false
      - LIBREOFFICE_DISABLE_ROUTES=false
      - LOG_LEVEL=info
    ports:
      - "127.0.0.1:3000:3000"
    resources:
      limits:
        cpus: '2.0'
        memory: 2g

  nginx:
    image: nginx:alpine
    container_name: pdf-secure-proxy
    restart: always
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - /etc/letsencrypt:/etc/letsencrypt:ro
    depends_on:
      - gotenberg

Note: We limit the CPU and memory consumption of the Gotenberg container to prevent a massive conversion batch from starving other vital system processes.

Step 3: Configuring the Nginx Reverse Proxy and Security

To safeguard the API from unauthorized access, we wrap Gotenberg behind an Nginx reverse proxy configured with Basic Authentication and TLS encryption. Create the nginx.conf file:

user nginx;
worker_processes auto;

events { worker_connections 1024; }

http {
    upstream pdf_backend {
        server gotenberg:3000;
    }

    server {
        listen 80;
        server_name pdf.yourcompany.com;
        return 301 https://$host$request_uri;
    }

    server {
        listen 443 ssl;
        server_name pdf.yourcompany.com;

        ssl_certificate /etc/letsencrypt/live/[pdf.yourcompany.com/fullchain.pem](https://pdf.yourcompany.com/fullchain.pem);
        ssl_certificate_key /etc/letsencrypt/live/[pdf.yourcompany.com/privkey.pem](https://pdf.yourcompany.com/privkey.pem);

        client_max_body_size 50M;

        location / {
            auth_basic "Restricted Corporate Access";
            auth_basic_user_file /etc/nginx/.htpasswd;

            proxy_pass http://pdf_backend;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
        }
    }
}

Generate your secure .htpasswd file using the htpasswd tool to ensure only verified corporate applications can invoke the API endpoints.

Step 4: Launching the Infrastructure

Execute the following command to download the microservices and run them in the background:

docker compose up -d

Verify that both containers are running healthy using docker compose ps.

---

Integrating the Service with Enterprise Applications

Once active, interacting with your private Gotenberg service is incredibly straightforward. It uses basic multi-part form requests to ingest source documents and instantly streams back the generated PDF binary.

Example: Converting an Office Document via cURL

Your back-end applications can send automated documents like invoices or spreadsheet data using simple HTTP requests. Here is a baseline command to convert a standard .docx contract:

curl --user admin:your_secure_password \
     --request POST '[https://pdf.yourcompany.com/forms/libreoffice/convert](https://pdf.yourcompany.com/forms/libreoffice/convert)' \
     --form 'files=@"/path/to/agreement.docx"' \
     --output '/path/to/output_agreement.pdf'

Example: Generating Reports from Dynamic HTML Templates

For pixel-perfect report generation, developers can feed Gotenberg an index.html file bundled with assets like localized fonts and styling guides. Gotenberg compiles the code in its sandbox environment and prints out a professional, print-ready document in milliseconds.

---

Production Monitoring and Maintenance Best Practices

To guarantee enterprise-grade availability, implement these three operational guidelines:

  • Health Check Probing: Monitor the /health endpoint regularly via internal uptime tracking systems to quickly discover stuck rendering engine sub-processes.
  • Automated Garbage Collection: Although Gotenberg cleans up after itself exceptionally well, configure an automated nightly cron job to clean dangling Docker system logs and temporary build volumes.
  • Horizontal Auto-scaling: If your office experiences massive concurrent spikes—such as end-of-month financial generation cycles—utilize Docker Swarm or a lightweight Kubernetes cluster to scale the Gotenberg service replica count dynamically behind your load balancer.
---

Conclusion

By taking ownership of your document conversion pipeline, your business successfully addresses data privacy vulnerabilities, streamlines software expenses, and enhances application flexibility. Deploying Gotenberg on a Docker VPS balances modern architectural agility with robust enterprise security, providing a highly reliable service that grows alongside your organization's operational demands.

Building a Private PDF Conversion Service for Corporate Offices Using Gotenberg on Docker VPS | DPTCloud