Some test text!

keyboard_arrow_down

Getting started

keyboard_arrow_down

Deployment options

keyboard_arrow_down

Webviewer Server

keyboard_arrow_down

Fundamentals

keyboard_arrow_down

Basics

keyboard_arrow_down

Annotations

keyboard_arrow_down

UI

keyboard_arrow_down

Legacy UI

keyboard_arrow_down

Advanced

keyboard_arrow_down

PDFNetJS Full

keyboard_arrow_down

PDF Processing API

WebViewer Server Container on Amazon Services

In this document
chevron_rightGetting Started
chevron_rightWebViewer Server on a Single Instance
chevron_rightAuto-Scaling WebViewer Server Setup
chevron_rightUsing the Server
chevron_rightUpdating your Server
chevron_rightDeleting your server
chevron_rightLogging
chevron_rightCreating Alarms and Notifications
chevron_rightSSH Access
chevron_rightTroubleshooting
chevron_rightHow it all works

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 built through a CloudFormation template.

linkGetting Started

There are several ways to host the WebViewer Server on Amazon. This guide will talk about hosting WebViewer Server on a single Amazon instance or using our Cloudformation template.

linkWebViewer Server on a Single Instance

This will be the easiest and quickest way to get going on Amazon. This guide will show you how to setup a single EC2 server and run the WebViewer Server container on it.

  1. Log into the Amazon Web Services console and select the EC2 service. Select the EC2 Dashboard and click Launch Instance. From here we will configure this EC2 server for launch.

  2. Select the Amazon Linux AMI for your server. Select Choose Instance Type - select the instance you want. We recommend at minimum the t2.medium instance. Select Configure Security Group and hit Add Rule. Set the type to HTTP. Select Review and Launch. In moments your server is will be online. The next step will setup and install Docker.

  3. To perform the next steps you need to SSH into the EC2 Server, this can be done by getting its EC2 Public Key and finding its DNS public name, both which should be visible on the details of the server. Once you've found these, perform a SSH on t he DNS public name. SSH can be done with a tool such as putty on windows and the ssh command on Linux.

  4. Once you've connected to the server, install Docker by executing these commands. The commands install Docker, start the service and set provide user permissions for Docker.

sudo yum update -y
sudo yum install -y docker

sudo service docker start
sudo usermod -aG docker ec2-user
  1. Install and run the WebViewer Server docker image. You must add your trial key to the WebViewer Server by setting DEMO_KEY in the command below to your trial key.
docker run --name webviewer-server -p 80:8090 -e INCLUDE_DEMO='true' -e TRN_PDFNET_KEY=DEMO_KEY pdftron/webviewer-server:latest
  1. Congratulations, you now have a WebViewer Server running on AWS. The server address will be the public DNS of the EC2 Server. You will be able to find a demo app at your publicdnsname/demo?s - or you can point your WebViewer application at this public dns name.

linkAuto-Scaling WebViewer Server Setup

In this portion of the guide we go over using our CloudFormation template/Marketplace offering to launch an auto scaling server architecture for running WebViewer Server. This auto-scaling server setup will provide a way to handle any incoming load by scaling servers out as required, and in as required.

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.

We offer the CloudFormation template directly on our website, which can then be used during stack creation on CloudFormation. Alternatively, you may subscribe to the AWS Marketplace offering. The template available on our website will be updated at more regular intervals.

  1. Download the CloudFormation template and navigate to CloudFormation. Select Create Stack. Once here select Upload a template to Amazon S3 and select the template that was downloaded from our website. Currently at version 1.0.4.

    Or subscribe to the AWS Marketplace. To use it, select your AWS region and click Subscribe on the marketplace page. Currently at version 1.0.2.

Once you've moved past the initial load of the CloudFormation template...

  1. The first page to appear will be for configuration. Most options available are in regards to customizing the scalability aspect of the WebViewer Server. Below are key notes about several configuration options.

    • Stack Name - All resources will be prefixed with the stack name. Required.
    • EC2Key - The private key the infrastructure resources will use. Required.
    • AvailabilityZone (1 & 2) - The zones your resources are run in, must be two seperate zones. Required.
    • Path - The path of your resources in AWS, should be ‘/’ unless there are special considerations. Required.
    • PDFNetKey - Your PDFTron license. The server will continue to run in demo mode until a PDFTron key is provided.
    • 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
  2. Hit next. The next page is entirely optional and can be used to setup any custom alarms. Click next.
  3. 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.
  4. 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 target the server with your application 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 2 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

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
  • Existing 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.

linkTroubleshooting

There are a handful of known issues:

Updating an existing stack after changing AWS::ECS::Service configuration in the template may cause failure on update as well as long delays before this failure notification.

  • This is caused by existing server instances not having enough resources to partition another container. Shutdown unused container instances so that CloudFormation is able to deploy replacements.

Deleting the stack results in failure occasionally.

  • This is due to known and inconsistent issues with how CloudFormation handles detaching Lambda Functions on private subnets from network interfaces. The only solution is to manually delete the afflicted network interface/subnet/vpc or continue attempting deletion until CloudFormation succeeds.

linkHow it all works

When deploying the server, the CloudFormation template is used as a blueprint for AWS infrastructure. It builds this infrastructure and pulls in our WebViewer Server Docker image. If you opted for the marketplace offering you will have 2 images for WebViewer Server created within your Elastic Container Repository (pdftron-balancer and pdfron-webviewerserver) on AWS. If you used the template available on our website, these images are pulled directly from DockerHub.

The diagram below shows how the CloudFormation auto scaling server setup is designed

The Elastic Container Service is the backbone of the system. It manages 2 types of container:

  • Load Balancer
  • WebViewer Server

The Elastic Container Service, in tandem with the auto scaling groups control container and server instance scalability. A series of Lambda functions manage performance measures, alarms and network mapping for these containers. This ensures high availability for the server.

At the front of everything sits an 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.