Securing Stirling-PDF: Implementing Nginx Reverse Proxy and Basic Auth

Stirling-PDF is a powerful, locally hosted web application that provides a comprehensive suite of tools for manipulating PDF files. While it is an excellent utility for local document processing, exposing the raw container port directly to your network—or worse, the internet—is a significant security risk. By default, Stirling-PDF lacks built-in authentication, meaning anyone with access to your server's IP and port can upload, modify, and download your sensitive documents. To secure Stirling-PDF in a Docker environment, the industry-standard approach is to place an Nginx reverse proxy in front of the container. This setup allows you to terminate connections, enforce authentication, and manage traffic flow without modifying the application code itself.

Understanding the Architecture

When you deploy a containerized application, the container typically exposes a port (e.g., 8080) that maps to your host machine. If you leave this port open, you bypass all layers of security. By introducing an Nginx reverse proxy, you create a gatekeeper. Nginx receives incoming requests, checks for valid credentials, and only if authorized, forwards the request to the Stirling-PDF container. This architecture also allows you to easily add SSL/TLS encryption later, which is critical if you plan to access your instance outside of your local network.

Prerequisites and Assumptions

This guide assumes you have already followed the steps to self-host-stirling-pdf-docker and have a working Docker Compose environment. You will need:

• A Linux server with Docker and Docker Compose installed.
• A basic understanding of Nginx configuration files.
• The apache2-utils package installed on your host (for generating password hashes).

Step 1: Generating Credentials

We will use HTTP Basic Authentication to restrict access. Nginx expects passwords to be stored in a specific format. First, install the necessary utility on your host machine:

sudo apt update && sudo apt install apache2-utils -y

Next, generate a password file. We will store this in a subdirectory named nginx within your project folder:

mkdir -p ./nginx
htpasswd -c ./nginx/.htpasswd your_username

You will be prompted to enter and confirm a password. The htpasswd command creates a file containing the username and a cryptographically hashed version of your password. Nginx will use this file to validate incoming requests.

Step 2: Configuring Nginx

Create a file named nginx.conf inside your ./nginx directory. This configuration defines how Nginx listens for traffic and how it handles the authentication challenge.

server {
    listen 80;
    server_name localhost;

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

        proxy_pass http://stirling-pdf:8080;
        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;

        # Increase timeout for large PDF uploads
        client_max_body_size 50M;
        proxy_read_timeout 300s;
    }
}

Key settings here include client_max_body_size, which is essential for Stirling-PDF because document processing often involves large file uploads. If you do not increase this, Nginx will return a 413 Request Entity Too Large error for any PDF over 1MB.

Step 3: Integrating with Docker Compose

Now, update your docker-compose.yml to include the Nginx service. You must ensure that the Nginx container can communicate with the Stirling-PDF container over the internal Docker network. Remove the port mapping from the Stirling-PDF service so it is no longer accessible directly.

version: '3.8'
services:
  stirling-pdf:
    image: frooodle/s-pdf:latest
    container_name: stirling-pdf
    restart: unless-stopped
    environment:
      - DOCKER_ENABLE_SECURITY=false # We handle security at the proxy level

  nginx:
    image: nginx:alpine
    container_name: nginx-proxy
    restart: unless-stopped
    ports:
      - "80:80"
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/conf.d/default.conf:ro
      - ./nginx/.htpasswd:/etc/nginx/.htpasswd:ro
    depends_on:
      - stirling-pdf

By using the service name stirling-pdf in the proxy_pass directive, Docker's internal DNS resolves the request to the correct container automatically.

Step 4: Verification and Troubleshooting

After updating your configuration, restart your services:

docker-compose up -d

Verify the setup by navigating to http://your-server-ip in your browser. You should be greeted by a browser-native authentication prompt. Enter the credentials you created in Step 1. If the credentials are correct, you will be directed to the Stirling-PDF dashboard.

Common Failure Modes

1. 403 Forbidden: This usually indicates that Nginx cannot read the .htpasswd file or the permissions are incorrect. Ensure the file is readable by the user running the Nginx process.
2. 502 Bad Gateway: This happens if Nginx cannot reach the Stirling-PDF container. Verify that both containers are on the same Docker network and that the service name in proxy_pass matches the service name in your docker-compose.yml.
3. 413 Request Entity Too Large: As mentioned, this is a result of the client_max_body_size being too small. Adjust this value in your nginx.conf and reload Nginx.

Operational Security Considerations

While HTTP Basic Auth provides a layer of protection, it is not a replacement for robust identity management. Basic Auth sends credentials in a base64-encoded format, which is not encrypted by default. If you are accessing your instance over an insecure network, your credentials could be intercepted. To fully secure your deployment, you should eventually implement SSL/TLS using Certbot or a reverse proxy manager like Traefik or Nginx Proxy Manager. These tools automate the acquisition of Let's Encrypt certificates, ensuring all traffic between your browser and the server is encrypted.

Furthermore, consider the physical security of your server. If the host machine is compromised, the .htpasswd file can be read. Always follow best practices for hardening your Linux server to minimize the attack surface of the underlying host.

Conclusion

Securing your Stirling-PDF instance is a critical step in maintaining a private and functional home lab. By leveraging Nginx as a reverse proxy, you decouple the security logic from the application, providing a flexible and standard way to control access. This setup not only protects your documents from unauthorized access but also prepares your infrastructure for more advanced security configurations like automated SSL termination and centralized logging. By following these steps, you ensure that your document processing workflow remains both efficient and secure.