Overview

A Cloud License allows you to use the features you have paid for PrizmDoc Server instances across a paid number of total logical CPU cores until your license expiration date. At runtime, the total number of logical CPU cores is tracked and, if bringing up a server exceeds the core limit, its functionality is disabled. In order to track the total number of logical cores in use, a Cloud License requires you to configure an AWS S3 bucket which all of your PrizmDoc Server instances can read and write from (see requirements below).

Despite the name, a Cloud License can be used for both on-premise and cloud deployments as long as your PrizmDoc Server instances have access to an S3 bucket which you own. However, a Cloud License has some disadvantages: 1) you must correctly configure an AWS S3 bucket and properly configure your PrizmDoc Server instances to access it, 2) renewing your license requires reconfiguration and redeployment, and 3) you cannot scale beyond the number of virtual CPU cores you paid for without upgrading to a new license.

Deprecation Notice

The Cloud License type has been deprecated, and the ability to run the product with a Cloud License will be removed in a future release. If you are currently using a Cloud License, we recommend you migrate to a new Metered License.

Requirements

NOTE: PrizmDoc Cloud Licensing does not support Docker orchestration systems, such as AWS Fargate/ECS/EKS, Google Kubernetes, Azure Container Instances, etc.

S3 Bucket with Appropriate Permissions Configured

To use a Cloud License, you need to provide an S3 bucket to PrizmDoc with read, write, and delete permissions:

listObjects

• AWS S3 listObjects docs
• Requires s3:ListBucket

putObject

• AWS S3 putObject docs
• Requires s3:PutObject

deleteObjects

• AWS S3 deleteObjects docs
• Requires s3:DeleteObject

At runtime, each of the PrizmDoc Server instances in your cluster will read and write extremely-small, temporary files into this bucket as part of licensing enforcement.

Usage

To set up a Cloud License, you will need to do the following:

1. Set up an S3 bucket.
2. Purchase a Cloud License from Accusoft.
3. Get your license key from the Accusoft customer portal.
4. Configure your PrizmDoc Server instances with the necessary AWS credentials.
5. Configure your PrizmDoc Server instances with your license key.

The sections below provide additional information for each step.

1 - Set up an S3 bucket

First, you must have an Amazon AWS account in order to create an S3 bucket. Log into your AWS account console and create an S3 bucket which PrizmDoc can read and write to at runtime. See the Amazon S3 documentation for more information on setting up an S3 bucket and acquiring credentials.

NOTE: We recommend that you create a dedicated AWS user and bucket with read/write credentials.

2 - Purchase a Cloud License from Accusoft

To purchase a Cloud License for PrizmDoc Viewer, contact info@accusoft.com.

During purchase, specify the maximum number of logical cores to be provided by the license. Make sure to account for production, support, and any ongoing development usage; you may want to consider purchasing separate licenses for both production and development.

3 - Get Your License Key from the Accusoft Customer Portal

Once purchased, visit the Accusoft Customer Portal to view your purchased license and provide the S3 bucket name that you will use for Cloud Licensing. After providing your S3 bucket name, your Cloud License key will be given to you. > NOTE: It is your responsibility to provide a valid S3 bucket and to ensure that you have the proper credentials to access that bucket.

1. Enter your Amazon S3 bucket name in the field provided and click Activate License:

   

   NOTE: You must enter your S3 bucket name correctly. Make sure there are no leading or trailing spaces! If you make a mistake, your license key will be unusable.

2. Select and copy all of the text in the License Key field below. This is your activated license key and you will need to save it for later use when configuring PrizmDoc Viewer on your server:

   

3. Click Download to go to the product download page and download your product.

4. Continue with Section 4 below.

4 - Configure Your PrizmDoc Server Instances with the Necessary AWS Credentials

When running PrizmDoc with a Cloud License on your server, it will require access to the Amazon S3 bucket you provided when your license was generated. It is important to note that PrizmDoc Server itself requires no knowledge of your S3 credentials. PrizmDoc Server accesses Amazon S3 assuming your credentials have been provided using one of the methods defined in the Amazon SDK documentation that do not require explicitly providing them to our product. As shown below, using method 1, 2, or 3 will provide access to AWS S3.

If you are new to Amazon Web Services (AWS), you should familiarize yourself with the Security Credentials to get an overview.

There are three options for configuring your AWS credentials for Cloud Licensing. They are listed in the order of recommendation:

1. Configure IAM roles for Amazon EC2 (if running on EC2), or
2. Configure the Shared Credentials File (~/.aws/credentials), or
3. Configure Environment Variables.

NOTE: When setting credentials, be sure that the user under which the PrizmDoc service is running is the same user for which you are configuring the credentials. For example, consider the case where you configure the credentials for your personal user, but PrizmDoc is running as the root user. In this case the service will start, but then shut down shortly after because the root user will be unable to access the S3 bucket specified in your Cloud License key.*

Examples using IAM Roles are beyond the scope of this topic, but if your cluster is running on AWS EC2 instances, you can find information about IAM Roles and their configuration in the Amazon IAM documentation.

An example using method 2 above, Shared Credentials Files, are shown below. You can configure a shared credentials file for the user under which PrizmDoc will execute:

In both Linux and Windows, the credentials file content is the same.

Example Credentials File Content

[default]
aws_access_key_id = your_access_key_id
aws_secret_access_key = your_secret_access_key

Credential files are stored under an .aws directory for the user under which PrizmDoc is executing. The credential file paths below are for an example called: prizmdocuser.

In Linux

/home/prizmdocuser/.aws/credentials

_NOTE: If your PrizmDoc Server is configured to start/stop with the system, you must modify the configuration section of /usr/share/prizm/pccis.sh script: set the AWS_HOME variable to the path of the directory which contains the AWS folder (.aws). For the example above, it will be AWS_HOME=/home/prizmdocuser._

When using Docker

Map the .aws directory to prizmdoc container's file system when starting the container:

docker run --rm --env ACCEPT_EULA=YES --publish 18681:18681 --volume $(pwd)/config:/config --volume $(pwd)/logs:/logs --volume $(pwd)/data:/data --volume $(pwd)/.aws:/root/.aws --name prizmdoc-server accusoft/prizmdoc-server

In Windows

C:\Users\prizmdocuser\.aws\credentials

Examples using method 3 above, Environment Variables, are shown below. You can configure your server to export the credentials to the environment for the user under which PrizmDoc will execute:

In Linux

Exporting environment variables under Linux is usually done in the user's .profile file in their home directory (e.g. for a user named prizmdocuser these would be added to /home/prizmdocuser/.profile). > NOTE: The following environment variables need to be configured on the Docker container since the licensing component in the app will use them to access the S3 bucket.

Example

export AWS_ACCESS_KEY_ID=your_access_key_id
export AWS_SECRET_ACCESS_KEY=your_secret_access_key

In Windows

Exporting environment variables under Windows is done in the Environment Variables control panel under the System Properties.

Example

5 - Configure Your PrizmDoc Server Instances with Your License Key

To configure a PrizmDoc Server instance to use a Cloud License key:

1. Update two values in your Central Configuration file (prizm-services-config.yml):

   • license.key - Set to your OEM License key (like 2.0.abc...).
   • license.solutionName - Set to your solution name (like My Product), chosen at the time of purchase. This value must match the value encoded in the license key itself.

2. Start/Restart PrizmDoc Server to apply the new license key.

Once PrizmDoc Server starts and reports healthy, you are licensed and ready for production traffic.

Limiting the Number of CPU Cores Used by Docker Containers

If you run multiple prizmdoc-server containers on the same host, or want to limit the CPU consumption for prizmdoc-server containers, you should use the CPU affinity mask when starting the container. This allows PrizmDoc to correctly count the logical CPU cores used by the container, as opposed to the total number of host's CPU cores. Use Docker run command parameter --cpuset-cpus to specify the affinity mask.

Example

This example assigns cores 0 and 1 for running the container:

docker run --rm --env ACCEPT_EULA=YES --publish 18681:18681 --volume $(pwd)/config:/config --volume $(pwd)/logs:/logs --volume $(pwd)/data:/data --volume $(pwd)/.aws:/root/.aws --name prizmdoc-server --cpuset-cpus 0-1 accusoft/prizmdoc-server