softvisiondev/webpdf repository overview

⁠webPDF - the PDF powerhouse

⁠TL;DR

$ docker run --name webpdf -p 8080:8080 softvisiondev/webpdf:latest

⁠Docker Compose

$ curl -sSL https://raw.githubusercontent.com/softvision-dev/webpdf-docker/master/10.0/docker-compose.yml > docker-compose.yml
$ docker-compose up -d

⁠Kubernetes

$ curl -sSL https://raw.githubusercontent.com/softvision-dev/webpdf-docker/master/10.0/kubernetes.yaml > kubernetes.yaml
$ kubectl apply -f kubernetes.yaml

⁠Red Hat OpenShift

$ curl -sSL https://raw.githubusercontent.com/softvision-dev/webpdf-docker/master/10.0/kubernetes-openshift.yaml > kubernetes-openshift.yaml
$ oc apply -f kubernetes-openshift.yaml

For more information, please read the Kubernetes deployment⁠ section below.

⁠Supported tags and respective Dockerfile links

• 10.0.x, 10.0, latest (10.0/Dockerfile)⁠ - Tags: 10.0.6
• 9.0.x, 9.0 (9.0/Dockerfile)⁠ - Tags: 9.0.6
• 8.0.x (8.0/Dockerfile)⁠ - Tags: 8.0.0
• 7.0.x (7.0/Dockerfile)⁠ - Tags: 7.0.0

latest and 10.0 always point to the newest 10.0.x release. Older patch releases are available as explicit tags (e.g. 10.0.3).

Version-specific docs live in 10.0/README-10.0.md, 9.0/README-9.0.md, 8.0/README-8.0.md, and 7.0/README-7.0.md.

⁠Quick reference

• Where to get help: the Docker Community Forums⁠, the Docker Community Slack⁠, or Stack Overflow⁠

• Where to file issues: https://github.com/softvision-dev/webpdf-docker/issues⁠

• Maintained by: the webPDF Docker Maintainers⁠

• Supported Docker versions: the latest release⁠

⁠What is webPDF?

webPDF⁠ is the centralized multi-platform PDF server solution that provides SOAP and REST Web services⁠ and a Web portal⁠. webPDF allows the creation and manipulation of PDF documents, including operations like digital signing, OCR and PDF/A conversion.

Overview of webPDF⁠

⁠Get this image

The recommended way to get the webPDF Docker Image is to pull the prebuilt image from the Docker Hub Registry⁠.

$ docker pull softvisiondev/webpdf:latest

To use a specific version, you can pull a versioned tag. You can view the list of available versions⁠ in the Docker Hub Registry.

$ docker pull softvisiondev/webpdf:[TAG]

⁠How to use this image

⁠Starting webPDF

Starting a webPDF instance is simple:

docker run --name webpdf -p 8080:8080 softvisiondev/webpdf:latest

... where webpdf is the name you want to assign to your container and latest is the tag specifying the webPDF version you want. See the list above for relevant tags.

⁠Exposing external port

docker run -p 8080:8080 softvisiondev/webpdf:latest

...where -p maps the container's port 8080 to the host's port 8080.

⁠Accessing webPDF

Based on the used -p parameter, you can access the webPDF portal by launching a web browser and go to http://localhost:8080/webPDF/.

⁠Health check

The image includes a built-in health check that monitors the server's availability. The health check uses the /webPDF/health endpoint and runs automatically:

• Interval: Every 30 seconds
• Timeout: 10 seconds per check
• Start period: 90 seconds (grace period after container start)
• Retries: 3 failed checks before marking as unhealthy

⁠Check container health status

docker ps

The STATUS column shows the health status (e.g., Up 2 minutes (healthy)).

⁠Detailed health information

docker inspect --format='{{json .State.Health}}' webpdf

⁠Manual health check

curl http://localhost:8080/webPDF/health

The health check is automatically used by orchestration platforms like Docker Swarm, Kubernetes, and Portainer for service management and load balancing.

⁠Configure volumes

Start webPDF with an attached configuration volume to keep your settings after updates.

docker run -p 8080:8080 -v webpdf-config:/opt/webpdf/conf softvisiondev/webpdf:latest

...where -v creates and attaches the volume named webpdf-config to the /opt/webpdf/conf path, where webPDF stores its configurations.

You can also keep the logs and the keystore files if you mount volumes for the folders /opt/webpdf/logs and /opt/webpdf/keystore.

docker run -p 8080:8080 \
  -v webpdf-config:/opt/webpdf/conf \
  -v webpdf-logs:/opt/webpdf/logs \
  -v webpdf-keystore:/opt/webpdf/keystore \
  softvisiondev/webpdf:latest

⁠Fonts

The webPDF container includes an extensive collection of fonts from various sources:

• MS Core Fonts: Arial, Times New Roman, Courier New, etc.
• MS Vista Fonts: Calibri, Cambria, Candara, Consolas, etc.
• Wine Fonts: Tahoma, Wingdings
• Liberation Fonts: Liberation Sans, Serif, Mono
• Noto Fonts: Noto Sans, Noto Serif, Noto Color Emoji
• Additional Fonts: DejaVu, OpenSymbol, Fira Code

⁠Add custom fonts

To add additional fonts, especially customized fonts, mount a volume for /home/webpdf/.fonts. The webPDF server uses fonts from the user's home folder webpdf.

docker run -p 8080:8080 -v webpdf-fonts:/home/webpdf/.fonts softvisiondev/webpdf:latest

The font folders used are displayed when the server is started and can be viewed via the console or the log files.

⁠List installed fonts

docker exec webpdf fc-list

⁠Environment variables

When you start the webpdf image, you can adjust the configuration of the webPDF instance by passing one or more environment variables on the docker run command line.

⁠JAVA_PARAMETERS

Allows passing Java VM options to the webPDF server startup.

Example: Set memory limits

$ docker run --name webpdf -e JAVA_PARAMETERS="-Xmx2048m -Xms1024m" softvisiondev/webpdf:latest

⁠LANG, LANGUAGE, LC_ALL

Linux environment variables for the language and encoding used in the image and for the webPDF server.

Default: de_DE.UTF-8

Example: Use English locale

$ docker run --name webpdf -e LANG=en_US.UTF-8 -e LANGUAGE=en_US.UTF-8 -e LC_ALL=en_US.UTF-8 softvisiondev/webpdf:latest

⁠TZ

Linux environment variable for the timezone used in the image and for the webPDF server.

Default: Europe/Berlin

Example: Use New York timezone

$ docker run --name webpdf -e TZ=America/New_York softvisiondev/webpdf:latest

⁠Shared memory

The webPDF server requires shared memory allocated to the container. You can configure the shared memory of the container with the --shm-size parameter or use shm_size⁠ in the docker-compose.yml file.

$ docker run --name webpdf -p 8080:8080 --shm-size=2gb softvisiondev/webpdf:latest

A shared memory of at least 2 GB is recommended.

⁠Non-root container

The webPDF container runs under the non-privileged (non-root) user webpdf with UID 10000 and GID 10000. Non-root container images add an extra layer of security and are generally recommended for production environments.

⁠Customize User and Group IDs

If you need to match the container's user with your host system's user for volume permissions, you can customize the UID and GID during the build process:

docker build --build-arg USER_UID=1000 --build-arg USER_GID=1000 -t webpdf:custom .

This is particularly useful when mounting host directories that require specific ownership:

# Build with custom UID/GID
docker build --build-arg USER_UID=$(id -u) --build-arg USER_GID=$(id -g) -t webpdf:custom .

# Run with host directory mount
docker run -p 8080:8080 -v ./config:/opt/webpdf/conf webpdf:custom

Note: The USER_UID and USER_GID build arguments can only be set during image build time, not at runtime.

⁠Complete example

Here's a complete example combining common options:

docker run -d \
  --name webpdf \
  -p 8080:8080 \
  --shm-size=2gb \
  -e JAVA_PARAMETERS="-Xmx2048m -Xms1024m" \
  -e TZ=Europe/Berlin \
  -v webpdf-config:/opt/webpdf/conf \
  -v webpdf-logs:/opt/webpdf/logs \
  -v webpdf-keystore:/opt/webpdf/keystore \
  -v webpdf-fonts:/home/webpdf/.fonts \
  softvisiondev/webpdf:latest

⁠Logging

The webPDF image sends the container logs to the stdout. To view the logs:

$ docker logs webpdf

or using Docker Compose:

$ docker-compose logs webpdf

You can configure the container's logging driver⁠ using the --log-driver option if you wish to consume the container logs differently. In the default configuration docker uses the json-file driver.

⁠Kubernetes deployment

The repository includes comprehensive Kubernetes manifests for deploying webPDF:

• kubernetes.yaml: Standard Kubernetes deployment (Docker Desktop, Minikube, EKS, GKE, AKS)
• kubernetes-openshift.yaml: Red Hat OpenShift-compatible deployment with Security Context Constraints (SCCs)

⁠Configuration initialization

Both manifests use application-level configuration initialization - no init containers required! The webPDF startup script automatically initializes missing configuration files from built-in defaults. This approach:

• Works without root privileges (OpenShift compatible)
• Supports individual file mounts (e.g., custom application.xml)
• Idempotent and self-healing
• Follows industry best practices as applied in other containers

⁠Standard Kubernetes

Quick start:

$ kubectl apply -f kubernetes.yaml

The container typically starts in 20-30 seconds. Access via:

• NodePort (default): http://<node-ip>:30080/webPDF/
• Or configure LoadBalancer/Ingress for production

Custom font options:

• HostPath: Mount local directory (default, adjust the path in manifest)
• EmptyDir: No custom fonts needed (container includes extensive font collection)
• PVC: For shared fonts across nodes (production)

⁠Red Hat OpenShift

The OpenShift manifest addresses platform-specific requirements:

• Compatible with restricted SCC (no root containers)
• Uses OpenShift Routes for external access with TLS
• emptyDir volumes instead of hostPath (hostPath forbidden)
• Dynamic UID/GID assignment from the project range

Quick start:

$ oc apply -f kubernetes-openshift.yaml
$ oc get route webpdf  # Get the external URL

Custom font options:

• EmptyDir: No custom fonts (default, container includes extensive font collection)
• PVC: For persistent custom fonts

Key differences:

For detailed OpenShift deployment instructions, see inline comments in kubernetes-openshift.yaml⁠.

⁠Build arguments

If you build the webPDF container with the Dockerfile, you can customize the build process with the following arguments⁠.

⁠BASE_IMAGE

Overrides the Debian base image used for all build stages.

Default: docker.io/library/debian:trixie-slim

Example:

docker build --build-arg BASE_IMAGE=docker.io/library/debian:trixie-slim -t webpdf:base-pin .

⁠LOCAL_PACKAGE

If this option is set to true, the Linux package is not fetched from the official package repository⁠, but the local file ./packages/webpdf.deb is used for the build process.

Example:

docker build --build-arg LOCAL_PACKAGE=true -t webpdf:local .

⁠WEBPDF_VERSION

Pins the webPDF Debian package version from the official repository. Leave empty to install the latest package from the repo.

Default: empty (latest from repo)

Example:

docker build --build-arg WEBPDF_VERSION=10.0.1-1 -t webpdf:10.0.1 .

⁠USER_UID and USER_GID

Set custom user and group IDs for the webpdf user (default: 10000).

Example:

docker build --build-arg USER_UID=1000 --build-arg USER_GID=1000 -t webpdf:custom .

⁠Testing

The repository includes test scripts to verify the Docker image functionality:

⁠Bash (Linux, macOS, WSL2, Git Bash)

cd 10.0
chmod +x test-docker.sh
./test-docker.sh

⁠PowerShell (Windows, Cross-Platform)

cd 10.0
.\test-docker.ps1

The test scripts verify:

• Image build success
• Container startup
• Health check functionality
• Font installation
• webPDF endpoint availability
• User permissions

⁠Configure test scripts

Both test scripts use the LOCAL_PACKAGE=true build argument by default, which requires a local webpdf.deb file in the ./packages/ directory.

To test with the package from the official repository instead, edit the configuration at the top of the script:

test-docker.sh:

LOCAL_PACKAGE="false"  # Use official repository

test-docker.ps1:

$LOCAL_PACKAGE = "false"  # Use official repository

⁠Technical details

⁠Base image

• Debian Trixie Slim (latest stable)
• Multi-stage build for optimized image size

⁠Architecture

The Dockerfile uses a 4-stage build process:

1. Stage 1: System fonts installation (MS Core Fonts, Noto, Liberation, etc.)
2. Stage 2: Custom fonts compilation (Vista Fonts, Wine Fonts)
3. Stage 3: Font consolidation
4. Stage 4: Final webPDF installation

This approach minimizes the final image size by excluding build tools and intermediate files.

⁠Security features

• Non-root user execution
• Chromium sandbox disabled (required for containerized PDF rendering)
• Modern GPG key management (/etc/apt/keyrings/)
• Minimal attack surface (slim base image)

⁠Development and support

If you have any questions on how to use webPDF or this image, or have ideas for future development, please get in touch via our product homepage⁠.

If you find any issues, please visit our GitHub Repository⁠ and write an issue.

⁠License

Please, see the license⁠ file for more information.