Introduction

The PrizmDoc Services are designed to run out-of-the-box on a single server. In the single-server mode, the PrizmDoc Services are listening on port 18681 by default and fulfilling requests entirely on the same server. There is no additional configuration to run in single-server mode. This mode is recommended if you have only one server hosting the PrizmDoc Services.

If your application requires more bandwidth or processing power than one server can handle, the PrizmDoc Services provide a mode that enables request load balancing and routing across multiple servers hosting PrizmDoc Server. This topic discusses the requirements and considerations for running the PrizmDoc Services in cluster mode.

Additional topics that support cluster mode:

NOTE: We will be defaulting to multi-server/cluster mode for PrizmDoc in a future release.

Cluster Mode

Before getting into the details of cluster mode, it’s important to understand two things about how the PrizmDoc Server generates and serves content:

The majority of requests the PrizmDoc Server handles are centered on document conversions or manipulations. These processes can be computationally expensive, so the PrizmDoc Server attempts to conserve as much CPU resources as possible by caching content as it's created.
Cached content is only stored locally on the server where it was created and it is directly tied to a specific resource created by the RESTful web service. Requests for existing resources must be handled by the PrizmDoc Server on the server that originally created it, otherwise errors will occur.

DEPRECATION NOTICE: Affinity tokens will be removed in a future release. We are moving towards eliminating the local cached data that makes server affinity necessary.

How It Works

The cluster mode of the PrizmDoc Server works by creating a new entry point on each server hosting the PrizmDoc HTTP Service. This new entry point becomes responsible for routing requests to the correct PrizmDoc Server, as well as load balancing requests for new RESTful web service resources over all the PrizmDoc Servers in the node.

Consider the diagram below which depicts an architecture that employs 3 servers hosting the PrizmDoc HTTP Service within a node. Looking deeper, notice that each server is hosting two entry points:

The Server Entry Point (SEP) will be listening on port 18682 by default. This is the main PrizmDoc HTTP Service entry point for the server. It is responsible for routing requests to the internal services running on the server. It is also the same entry point that handles requests from your application in single-server mode. However, in cluster mode your application should not send requests directly to the SEP, but instead the requests should be made to the Cloud Entry Point.

The Cloud Entry Point (CEP) will be listening on port 18681 by default. In cluster mode, the CEP is responsible for routing requests to the correct PrizmDoc Server. If you are creating a new RESTful web service resource, the CEP will direct that request to a PrizmDoc Server it chooses.

If you are working with an existing resource, the CEP will ensure that the request is forwarded on to the server which originally created the resource. Any CEP can route any request to the correct server. This allows you to use a simple load balancer in front of your PrizmDoc Servers; simply have the load balancer send incoming requests to any CEP on any server and the CEP's will ensure that the requests are routed to the appropriate machine.

Step 1 - Configuration

After installation, the PrizmDoc HTTP Service will be running in single-server mode. To enable cluster mode:

Stop the PrizmDoc Server.
Open the Central Configuration file in a text editor.

The file paths for the Central Configuration file are:
- Docker: <config_folder>/prizm-services-config.yml, where <config_folder> is the folder that you mapped as /config when creating the container. See Installing / Using Docker for more details.
- Windows: C:\Prizm\prizm-services-config.yml (assuming the standard install location.)

Set the network.clustering.enabled value to true, and make sure the network.publicPort and network.clustering.clusterPort values exist and are assigned to valid port numbers:

network.clustering.enabled: true

network.clustering.clusterPort: 18682 # Server Entry Point for every server in the cluster

network.publicPort: 18681 # Cloud Entry Point

Optionally, set the network.clustering.servers value to an array of address values corresponding to each PrizmDoc Server on the network node. For example:
```
network.clustering.servers: ["192.168.0.1", "192.168.0.2", "192.168.0.3"]
```
Save and close the Central Configuration file.
Start the PrizmDoc Server.

NOTE: If your application makes requests to the PrizmDoc service from another server, ports 18681 and 18682 (or other port values you choose) will need to be opened in the firewall for each server hosting the PrizmDoc service.

Step 2 - Start-Up

Once the PrizmDoc HTTP Service has been configured and is running on each server, there is one more critical step you must perform before the Cloud Entry Points will be able to handle requests successfully.

In this step you will inform the Cloud Entry Point on each PrizmDoc Server of the other available PrizmDoc Servers in the same network node. This list allows any CEP to route requests for existing resources to the correct PrizmDoc Server that originally created it, as well as load balance requests for new resources across all servers.

The list of servers is set by a HTTP PUT request to each Cloud Entry Point. Below is an example of the request that would be sent to each Cloud Entry Point (given the sample architecture shown in the diagram above):

Example

PUT http://192.168.0.1:18681/PCCIS/V1/Service/Properties/Servers {
    "servers": [
        {
            "address": "192.168.0.1",
            "port": "18682"
        },
        {
            "address": "192.168.0.2",
            "port": "18682"
        },
        {
            "address": "192.168.0.3",
            "port": "18682"
        }
    ]
}

This request would be repeated for the remaining two PrizmDoc Servers, the only change being the port specified in the HTTP request.

If the network.clustering.servers value was set in the Central Configuration file during the configuration step, the list of servers will automatically be initialized to this list on start-up. It may still be overridden by a HTTP PUT request to the Cloud Entry Point, but will initialize to the configured value again on subsequent start-ups unless the network.clustering.servers value is changed in the Central Configuration file.

Step 3 - Scaling

When PrizmDoc Servers are added or removed from the node, it is important that the list of servers held by each Cloud Entry Point is updated to reflect the servers that are actually active. Otherwise, requests will begin failing when routed to a server that does not exist, and new servers will not receive their fair share of new requests because not every PrizmDoc Server in the node is aware of them.

Keeping the server lists updated is a matter of repeating the requests described in the Start-up section above, only with updated JSON data that includes the new list of active servers.

HTTPS Protocol Support

If instances within your PrizmDoc cluster need to communicate over an untrusted network, or if you need additional security within your local network, you may want to set them up to support the HTTPS protocol. See Security Guidance for details.