Overview

PSPDFKit Server is our server-side component used by PSPDFKit for Web and PSPDFKit Instant. It’s delivered as a Docker container that you deploy to your own infrastructure. Your PSPDFKit-powered apps then connect to it.

PSPDFKit Server requires a PostgreSQL database and dedicated file storage, the latter of which can be either the PostgreSQL database itself, or any S3-compatible object storage.

  • PSPDFKit for Web

    PSPDFKit Server preprocesses uploaded documents into a format that PSPDFKit for Web can render, and it stores annotations. PSPDFKit for Web intelligently downloads pages on demand, so even large documents can be browsed quickly.

    More information can be found in the PSPDFKit for Web guides.

  • PSPDFKit Instant

    As with PSPDFKit for Web, PSPDFKit Server stores uploaded documents and annotations. PSPDFKit for Android, iOS, and Web connect to PSPDFKit Server to synchronize annotations and download documents.

    More information can be found in the guides for each platform.

Use Cases

All workflows powered by PSPDFKit Server require creating a document either by uploading a file in one of the supported file formats or by sending a URL the file can be fetched from.

When uploaded, document files are stored in the asset storage, which can be one of the supported asset storage backends.

Annotations and other metadata are always stored in PostgreSQL, irrespective of the document having been created by upload or from a URL.

Below you’ll find a few examples of what you can do with PSPDFKit Server.

Please note that, depending on your license, some document file formats and use cases may be restricted.

Storing a File Uploaded by an End User

When you want to store a file uploaded by an end user, the file needs to be uploaded to your service first, and then forwarded to PSPDFKit Server.

PSPDFKit Server is used to store PDF documents and their annotations. Your server has access to a rich HTTP API.
  1. Users upload a document to your backend.
  2. Your backend forwards the uploaded PDF file to PSPDFKit Server. In return, it receives a document identifier. On your server, you only have to store the identifier; we store the PDF document, its annotations, and the meta information.

Creating a Document by Upload

When you create a document by upload, you send the file to PSPDFKit Server, which will manage the entire document lifecycle.

Your service uploads the document to PSPDFKit Server and receives a document ID back.
  1. Your service uploads the document to PSPDFKit Server, which stores the document in the asset storage and stores the metadata in PostgreSQL.
  2. Your service receives the document ID back, which it can use to reference the document later.

Creating a Document from a URL

When you already have an existing data store for your files or prefer not to store them with PSPDFKit Server, you can create a document from a URL.

When operating on a document from a URL, PSPDFKit Server will fetch the file using the provided URL and cache it in the node file system.

Your Server sends a document’s URL to PSPDFKit Server and receives a document ID back.
  1. Your service sends a document’s URL to PSPDFKit Server, which makes a request to the URL to retrieve the document.
  2. The document service returns the document, and PSPDFKit Server saves it and its metadata in the asset storage and PostgreSQL.
  3. Your service receives the document ID back, which it can use to reference the document later.

Annotating a Document

After you create a document, you can easily annotate it via the Web Viewer, Web SDK, or Server APIs. Annotations are automatically persisted in the PostgreSQL database.

PSPDFKit for Web sends new annotation data to PSPDFKit Server, which saves it in the database.
  1. PSPDFKit for Web sends new annotation data to PSPDFKit Server, which stores it in the database.
  2. PSPDFKit Server returns the annotation ID to the Web SDK.

Multiple Users Annotating the Same Document

If you need multiple people to annotate independent copies of the same document, you don’t need to upload the document multiple times. Instead, you can assign a different Instant layer to each person. PSPDFKit Server will maintain a completely different set of annotations for each layer, thereby saving storage space.

You declare different layer names in the JWT used for authentication to create different perspectives of the same document.
  1. Your service provides your web application with JSON Web Tokens (JWTs) used for authentication. There are two different users: Both use the same document, but each of them uses a distinct Instant layer.
  2. Each user creates an annotation in their own layer. Annotations in different layers are completely separate, and annotations in one layer can’t be seen in any other layer. This approach can be used to separate annotations created by distinct users or by different document perspectives, e.g. marking up important information in the document and reviewing it.
  3. Each viewer instance only receives annotations created in its own layer, thereby maintaining the separation of content between users.
  4. A single document can have as many layers as you need. PSPDFKit will efficiently use the same underlying asset, generating layer-specific PDF files only when needed (e.g. if you want to download the PDF for a user’s layer).

Editing a Document

When you edit a document, for example, by rotating all pages, PSPDFKit Server saves a new asset for that document and updates all relevant annotations.

You rotate a document page and PSPDFKit Server stores the new PDF file.
  1. Your service requests that the Server rotates all pages of the document. PSPDFKit Server retrieves the document from the asset storage for processing.
  2. PSPDFKit Server transforms the document, rotating all of its pages.
  3. PSPDFKit Server persists the transformed document in the asset storage without deleting the original. It returns the new document’s properties to your service.

Signing a Document

When you digitally sign a document with a certificate-based signature, PSPDFKit Server will use your configured signing server to calculate and apply a document-wide digital signature. As a result, PSPDFKit Server will save the signed PDF as the new asset for the document. The old file is kept as the original asset for the document.

You digitally sign a document page and PSPDFKit Server stores the new PDF file
  1. Your service tells PSPDFKit Server to sign the document. The Server retrieves the document from the asset storage.
  2. Server sends the digest of document content to the configured signing service. The signing service creates a signature by encrypting the digest using an asymmetric cryptography algorithm, and it then returns it to the Server. The signing service can be the same service that made a signing request to the Server.
  3. PSPDFKit Server embeds the signature in the document and saves the signed document in the asset storage, preserving the original. The information about the newly created signature is returned to the Server.

Requirements

Supported Cloud Database Services

We regularly release new updates, which are announced via Twitter, our blog, and a newsletter you can subscribe to.

Please see the changelog for details of what’s new in each release.

If you experience any problems with PSPDFKit Server, please look at our Troubleshooting section, or contact support.