Cluster setup

note

First, read the general definitions to make yourself familiar with the terms used in the cluster context.

Before you start setting up the cluster, make sure that all requirements for operation are met. Also make sure that you have access data for the Redis server and the Shared File Storage. This data is required during setup.

Now follow the steps below to set up the cluster.

Requires a separate license

Make sure that you have a corresponding license key for operating a cluster. If not, or if you are not sure, please contact support.

Install nodes

Install the required number of webPDF servers on the platform of your choice.

Even though the individual servers can have different platforms, we still recommend using a uniform platform. The best way is to use Docker containers, as this makes it easiest to establish a uniform configuration of the nodes. This reduces problems in the operation of the cluster and makes it easier to replace individual nodes.

Important

All servers must have the same installation version of webPDF.

Choose coordinator

Set one of the installed servers as the coordinator. Enter the license for the cluster via the Admin Portal on this server. The other servers, which will become members, do not require a license, as they will receive one later from the coordinator.

On the coordinator server, define all settings that should apply to all servers. These are, for example, settings such as the ports, the authorization used or the web services activated. Configure the server completely according to your requirements before continuing with the setup.

tip

Check the coordinator server in standalone mode with your application/integration for the correct and desired functionality before proceeding.

Start the coordinator and log in to the Admin Portal.

Create cluster

In the Admin Portal, go to Cluster (1) in the toolbar and select Create to start the cluster creation.

Enter a unique name (1) for the cluster in the following dialog. This name must be unique and not yet exist in the network. Make a note of this name, as it will be required later for setting up the member nodes.

Specify a name for the node (2). If you do not enter a name, the host name of the system is automatically used.

Press Save to save the settings.

To apply the settings and restart the coordinator, click on Restart. Restarting the coordinator sets up the cluster during startup.

After restarting and logging into the admin portal again, you will see the new status of the server.

In addition to the status and role display in the toolbar (1), there is a new Cluster information function in the sidebar (2). This displays all information about the current cluster and all nodes.

The information under Cluster (3) is important as you will need it for further setup. Make a note of this information or copy it to a file from where you can insert it again later.

• Cluster name: Unique name of the cluster.
• Cluster key: Unique key for the cluster that allows access for other nodes.
• Namespace: Unique key for the Redis server under which all nodes store the data (prefix key for the data structures).
• Maximum node count: Maximum number of nodes in the cluster, defined by the license.

note

The cluster key is the unique key of the cluster, which serves as the access and encryption key in the cluster. It is not possible to join the cluster without this key. If this is lost, the cluster must be completely reconfigured.

Configure session, documents and files

After the basic setup of the coordinator node, the storage of the Sessions, Documents and Files must still be configured for it. These are the central storages for the cluster, which all nodes of the cluster use in order to have a common data storage.

The Sessions and Documents are stored in a Redis server.

note

The installation and setup of the Redis server is not part of this documentation. The procedure can be found in the official Redis documentation.

Session

In the toolbar, go to Cluster and then Session (1). Switch the dialog to Redis (2).

Enter the address of the Redis server in the configuration dialog (3).

Check the settings with the Test button (4). This establishes a connection to the Redis server and checks whether it can be used.

The settings are accepted and saved with Save (5).

Documents

Repeat the Session setting for the document metadata with the Documents button in the toolbar.

• Change to Redis
• Enter the address of the Redis server
• Execute Test button
• Save to save the settings

Files

Call up the Files function (1) in the toolbar under Cluster to configure the shared storage of the files.

In the dialog, you can select the Service (2) for the Shared File Storage:

• NFS (Network File System)
• SMB (Server Message Block)
• MinIO (S3 Compatible Storage)

Depending on the selected service, set the access data and click on Test (3) to check the settings.

The settings are accepted and saved with Save (5).

Restart and test coordinator Node

Once the entire configuration has been completed, you must restart the coordinator to activate the configuration.

Check the settings you have made by connecting the node to your applications or converting documents via the Portal.

caution

You should only continue with the configuration once the coordinator node is functioning correctly.

Add member nodes

In the next step, the member nodes can be added to the cluster. These member nodes adopt the settings of the previously set up coordinator node, including the connection settings to the Redis server and the shared file storage.

Select Join (1) in the toolbar and enter the corresponding data (2) in the dialog.

• Cluster name: Name of the cluster that was defined in the coordinator setup.
• Node name: Unique name of the nember node in the cluster
• Cluster key: Unique key that is displayed on the coordinator under the Cluster information.

After saving the settings with Save and Restart the server, the server joins the cluster as a member node.

The status of the cluster (see Create cluster) can also be displayed on the member node. You can check the status of the new node there (1).

In the detailed information, you can see the information of the member node and the updated status of the entire cluster (2).

You can now repeat the steps for other servers to add them to the cluster as nodes.

note

Please note that you cannot change the settings for Session, Files and Documents under Cluster in the toolbar, as these settings are provided by the coordinator in order to have them uniformly in the cluster.

Gateway

Once all the nodes in the cluster have been installed and set up, the gateway for central access to the nodes and web services must be configured. This must be done individually, depending on the gateway solution used. The instructions and procedure can be found in the respective solution documentation.

The Gateway used must forward the following base URIs (and all sub-paths) for the web services to the nodes:

• SOAP: /webPDF/soap/
• REST: /webPDF/rest/

To query the availability of a node, the gateway can use the Health API under /webPDF/health/ready.

Check cluster

When all the components of the cluster have been set up and started, you should check the functionality of the cluster.

You can check the status of all nodes in the cluster via Cluster information. All nodes should be started and the Node state should be green.

You can also use the portal for an initial test. Open the Portal via your gateway and process a series of documents.

If this test is also successful, then the final step is to connect the cluster to your application and use webPDF.