Horizontal Scaling

PSPDFKit Server has been deprecated and replaced by Document Engine. To start using Document Engine, refer to the migration guide. With Document Engine, you’ll have access to robust new capabilities (read the blog for more information).

PSPDFKit Server supports horizontal scaling via connecting multiple server nodes to your Postgres database.

This allows you to scale PSPDFKit Server in cloud environments like Amazon EC2 Container Service (ECS), Azure Kubernetes Service (AKS), and Google Kubernetes Engine (GKE). Deployments as a pod in a Kubernetes environment, on Docker Compose, or to Docker Swarm are also fully supported.

Whenever you start a new PSPDFKit Server node and connect it to your existing database, it will register itself with your database, and from then on, it will automatically receive and broadcast updates of all the changes made to your documents.

Configuration

Please note that all nodes have to use the same configuration. Always check docker-compose.yml to verify the configuration. Please also ensure all nodes are running the same PSPDFKit Server version.

❗Important: Since the local asset storage backend stores all assets within a Docker instance, it doesn’t work with the deployment of multiple nodes. Please migrate to S3 or to our built-in asset storage backend before deploying multiple nodes. See our guide on storage migration for information on how to migrate your asset storage backend.

Load Balancing

We recommend using a load balancer to distribute clients across your nodes.

Cloud Deployments

You can use load balancing solutions from your cloud platform provider:

Custom Deployments

You can use nginx load balancing. If you’re using Docker Compose, you can start by adding a new service configuration:

nginx:
  image: nginx
  volumes:
    - ./nginx.conf:/etc/nginx/nginx.conf:ro
  command: [nginx, "-g", "daemon off;"]
  depends_on:
    - pspdfkit
  ports:
    - 8000:80

The configuration mounts an nginx.conf file. A minimal version of that file could be:

user  nginx;
worker_processes  2;

events {
    worker_connections 500;
}
http {
    access_log /dev/stdout;
    error_log /dev/stderr;

        server {
              listen 80;
              resolver 127.0.0.11 valid=5s;
              set $upstream pspdfkit;

              location / {
                proxy_pass http://$upstream:5000;
                client_max_body_size 2048m;
                proxy_http_version 1.1;
                proxy_set_header Upgrade $http_upgrade;
                proxy_set_header Connection "Upgrade";
              }
        }
}

In the configuration, instruct nginx to resolve the pspdfkit upstream via Docker’s built-in DNS, which returns the IP address of one of the running pspdfkit containers. You can read more about resolvers and their limitations in the nginx documentation about resolvers.

Finally, you need to change the ports definition in the pspdfkit container definition in docker-compose.yml to avoid port clashing on the host machine:

pspdfkit:
  ports:
    - "5000"

After making these changes, you should be able to call docker-compose up --scale pspdfkit=3 and open the dashboard at http://localhost:8000/dashboard. If you look at the Docker Compose logs, you should see HTTP replies from different PSPDFKit Server instances.

Dashboard

The dashboard shows you all of the currently connected nodes, along with their IDs, PSPDFKit Server versions, IP addresses, and times of first connection.

Caching

Check out the Cache guide for more information on how to improve caching in a PSPDFKit Server setup with multiple nodes.

Licensing

Your license will define the number of servers that can be used. If you have questions, please contact our sales team for details.