Some test text!

WebViewer Server Container on the Amazon Web Services Marketplace

In this document
chevron_rightGetting Started
chevron_rightSetting up the server
chevron_rightUsing the Server
chevron_rightUpdating your Server
chevron_rightDeleting your server
chevron_rightLogging
chevron_rightCreating Alarms and Notifications
chevron_rightSSH Access
chevron_rightHow it all works
chevron_rightThe Annotation Server

This guide will show you how to build a highly reliable auto scaling server backend that will automatically work with your WebViewer based application to display documents. This server backend is offered through the Amazon Web Services Marketplace and makes use of CloudFormation to build the backend infrastructure.

linkGetting Started

Prior to starting this guide, you should already have an Amazon Web Services account that is able to use these features: EC2, VPC, Lambda, CloudWatch, CloudFormation, IAM, RDS, ACM and the Elastic Container Service.

linkSetting up the server

  1. The first step is subscribing to the Marketplace offering, to do so navigate to this link. On this page, scroll down and select the WebViewer AWS fulfillment option.
  2. Return to the top of the page and click Subscribe. Follow the directions from here until you are guided to a launch page. Launching will send you to CloudFormation, this is what will build your infrastructure. Follow the prompts and select next.
  3. On this page, you should see a series of options. Much of these have to do with customizing the scalability aspect of the WebViewer Server. Below are key notes about several configuration options.
  4. Stack Name - All resources will be prefixed with the stack name. Required.
  5. EC2Key - The private key the infrastructure resources will use. Required.
  6. AvailabilityZone (1 & 2) - The zones your resources are run in, must be two seperate zones. Required.
  7. Path - The path of your resources in AWS, should be ‘/’ unless there are special considerations. Required.
  8. PDFNetKey - Your PDFNet license. The server will continue to run in demo mode until a PDFNet key is provided.
  9. SSLServerCertificateARN - required to run the server with HTTPS, to setup a SSL Certificate on AWS we suggest using the Certificate Manager: https://docs.aws.amazon.com/acm/latest/userguide/acm-overview.html
  10. The Annotation Cluster Configuration is for usage with our anonymous annotation feature (beta). If you do not wish to use this feature, set AnnotationsEnabled to false.
  11. If using the anonymous annotations feature with the Annotation Cluster, your DatabasePassword must be at least 8 characters.
  12. Running the server with EnableDebugMode set to true can be dangerous. Do not set this to true in a production environment. If any required options are missing - the stack will fail to be built and return with the cause of the issue. Click next to proceed.
  13. This page is entirely optional and can be used to setup any custom alarms. Click next.
  14. On this page, check the box titled I acknowledge that AWS CloudFormation might create IAM Resources. Click Create. In approximately 15 minutes your stack will be created and ready to go.
  15. Once the stack creation has completed, you can select Outputs in the dropdown menu on CloudFormation. This will show links to the resources created.

linkUsing the Server

Now that your server has built you have a complete WebViewer backend for viewing documents. To direct your applications at this server you need to find the DNS name of the main load balancer. The load balancer will be prefixed with your stack name. It can be also found by:

  1. Access the Outputs section of your stack in CloudFormation.
  2. Select the link to the LoadBalancer.

Any certificates or domains you are using for the WebViewer Server should be tied to this DNS name. From here, you can use this DNS name in your WebViewer initializer as directed by the WebViewer Server guide.

A demo of the WebViewer Server’s capabilities can also be found at: your-load-balancer-address/demo?s

linkUpdating your Server

linkUpdating WebViewer Server settings

  1. Navigate to CloudFormation. Right click on your stack and select Update Stack.
  2. Upload the previously used CloudFormation template.
  3. Continue to configuration and adjust the settings as required.
  4. Confirm the stack update.

linkUpdating the server with a newer version

  1. Navigate to CloudFormation. Right click on your stack and select Update Stack.
  2. Upload your new CloudFormation template and continue through the setup process. Your old settings should be present. Review the remaining settings to ensure that no changes are required for the version update.
  3. Confirm the update, and wait till it has completed. May take anywhere from 15 minutes to an hour depending on the required changes.

linkDeleting your server

  1. Navigate to CloudFormation.
  2. Right click on your stack and select ‘Delete’.
  3. Deletion may take anywhere from 15 minutes to an hour. After deletion is completed, all resources relating to the stack will be gone.

linkLogging

All logs for the pdftron server will be placed under a single log group in CloudWatch. This log group can be found in the Outputs of your stack under PDFTronCloudWatchGroup. The log group name will be prefixed with your stack name.

Contained within the group will be 3 types of log, one for each container. The logs within the group represent each ECS cluster and are as follows:

  • HAProxy Cluster - pdft-internal-load-balancer
  • WebViewer Server cluster - pdft-pdf-server
  • Annotation cluster - pdft-annot-server

linkCreating Alarms and Notifications

WebViewer Server does not come with built in alarms to notify users on server state changes. These can be user added. Below are some key metrics that could be used for your alarms and notifications:

  • Container Health
  • Instance Health
  • Exisiting scaling alarms used by WebViewer Server
  • Log activity

https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html

linkSSH Access

  1. Update the stack with the last used template on CloudFormation.
  2. On the options page, set EnableSSHBastionServer to ‘true’. Continue through the configuration till you have successfully updated the server.
  3. Go to EC2, find the server with the security group ‘SSHServerSG’. Find its public IP and use this to SSH, along with the EC2Key you specified during configuration.
  4. Upload the EC2Key file to this server through SSH.

While using SSH on this server, you will be able to access any private IP address used by your WebViewer Server stack using your EC2Key and SSH.

linkHow it all works

This section covers more in detail how the Marketplace Server functions. Below is an overview diagram of our architecture.

When you subscribe to the WebViewer Server on the Marketplace, you gain access to 2 items:

  • A CloudFormation template
  • An Amazon Machine Image (AMI)

On first build of the WebViewer Server, the AMI will build and upload two container images to your Elastic Container Repository (ECR). These images will be titled ‘pdftron-balancer’ and ‘pdftron-webviewerserver’. The CloudFormation template is what controls this build process for the server and the surrounding infrastructure.

When using the CloudFormation template the build infrastructure is as follows:

The Elastic Container Service is the backbone of the system. Its container service manages 3 containers:

  • HAProxy Internal Load Balancer
  • PDFTron SDK (PDF) Server
  • PDFTron Annotation Server (beta)

The Elastic Container Service, in tandem with Auto Scaling Groups - controls the autoscaling of the system. A series of Lambda functions manages performance measures, alarms and network mapping for these containers. This ensures high availability for the server.

At the front of everything sits a AWS Classic Load Balancer. The internal network is private and heavily restricted to ensure security. As a result, the AWS Classic Load Balancer is the only public facing part of the system and gives access to the main functionality required for application development with WebViewer.

linkThe Annotation Server

The annotation server is a beta option offered that can easily be turned off and on by setting AnnotationsEnabled on Stack creation. It currently allows for anonymous browser session based document sharing and real time annotating. Enabling this will add a relational database for managing user annotations and another server cluster for managing annotation servers.