Configure Deployed Self-Hosted API

How to configure Self-Hosted API deployments subscribed to from the AWS Marketplace.

AWS Marketplace

Updating a CloudFormation Deployment

Self-Hosted API products deployed via CloudFormation are configured during Stack creation. If you would like to change the configuration of an existing deployment, follow the instructions below.

To update an existing Self-Hosted API on AWS deployment:

After submitting the build request, you will be taken to the CloudFormation Stacks page. There you will see the status of your Stack. It will likely be UPDATE_IN_PROGRESS.

Click on the Stack name for additional information. When the Self-Hosted API is finished updating, the Stack status will be UPDATE_COMPLETE.

Configure an AMI Deployment

Start the Docker Daemon

For this process, you will need to have already launched an instance by following the AMI Deployment guide.

# Run the Docker container.
# -d (--detach) runs the container in the background.
# -p (--publish) binds port 3000 of the Container to port 80 of the server.
# --restart sets policy to automatically restarts the Container if it stops.
# :latest runs the most recent version of the Container available.

docker run -d -p 80:3000 --restart always pdf_toolkit_self-hosted_api:latest

# Run the Docker container.
# -d (--detach) runs the container in the background.
# -p (--publish) binds port 3000 of the Container to port 80 of the server.
# --restart sets policy to automatically restarts the Container if it stops.
# :latest runs the most recent version of the Container available.

docker run -d -p 80:3000 --restart always pdf_forms_pro_self-hosted_api:latest

# Run the Docker container.
# -d (--detach) runs the container in the background.
# -p (--publish) binds port 3000 of the Container to port 80 of the server.
# --restart sets policy to automatically restarts the Container if it stops.
# :latest runs the most recent version of the Container available.

docker run -d -p 80:3000 --restart always pdf_office_pro_self-hosted_api:latest

sudo systemctl start docker

Controlling the Container

The following commands control the Docker container:

# View the running container and retrieve it's randomly generated name.
docker ps

# Stop the Docker server.
docker stop <container_name>

# Remove the container.
docker rm <container_name>

Environment variables

Above, using the docker run command, we started the server using the default configuration. As shown below, there are a number options that can be customized for the pdfRest service through its environment variables. Invoke environment variables by using -e with the docker run command.

Examples for starting server with customized configurations

# Run the pdfRest Self-Hosted API server so that processed documents
# are deleted in 30 minutes. Files are permitted to process for
# a maximum of 60 minutes.

docker run -d -p 80:3000 --restart always \
-e REMOVE_ORIGINAL_PROCESSED=1 \
-e MAX_PROCESS_TIME=3600 \
pdf_toolkit_self-hosted_api:latest

# Run the Forms Pro API so that processed documents are not deleted
# and the maximum uploaded file size is 10MB.

docker run -d -p 80:3000 --restart always \
-e REMOVE_ORIGINAL_PROCESSED=0 \
-e MAX_UPLOAD_SIZE=10 \
pdf_forms_pro_self-hosted_api:latest

Installing msCoreFonts

Microsoft Core Fonts are not licensed to be distributed with pdfRest API products but they are freely available from SourceForge for you to install. These are optional when deploying the pdfRest API and enable the following features:

• Support maximum file size reduction with Compress PDF by enabling font subsetting
  • Subsetting the fonts that are embedded in the document is an important step to reduce PDF file size. The subset of the font contains only those font characters actually used in the PDF document.
• Support font embedding, a required step to Convert to PDF/A
  • Embedding fonts in your output PDF document ensures that the document can be opened and viewed on any machine, because the fonts travel with that document. Quite literally, the necessary font files are saved within that PDF file. This is required for all PDF/A specifications to support long-term preservation.
• Expand the set of supported fonts that may be used with Watermark PDF.
  • Once installed, msCoreFonts are available for use with the Watermark PDF API Tool, expanding the set of fonts that can be applied with a text-based watermark.

Installing msCoreFonts

These steps will help you install the standard set of fonts provided by Microsoft, known as the Microsoft core fonts.

sudo rpm -i https://downloads.sourceforge.net/project/mscorefonts2/rpms/msttcore-fonts-installer-2.6-1.noarch.rpm

sudo node apply_settings.js

Manually Create an Elastic File System

Create an EFS

An Elastic File System is an optional infrastructure component. If you have two or more pdfRest Self-Hosted API products or instances and require any of the following, you will need to configure an EFS:

• Shared document storage between instances
• The ability to chain API calls between different products, such sending a document from PDF Toolkit to PDF Forms Pro.
• Most scenarios where instances are behind a Load Balancer

Follow these instructions to manually set up an EFS for use with your Self-Hosted API. Please contact us for any assistance with Self-Hosted configuration.

1. Create an Application Load Balancer.
2. Copy the Public DNS of the Load Balancer. It will be used in future steps.
3. Create instances of any pdfRest Self-Hosted API products using the AMI deployment guide.
4. Create your Security Groups.
5. Create your Elastic File System.
6. Mount the EFS on the EC2 instance.
7. Modify the /etc/fstab configuration file.
8. Modify the permissions on the directory:
   
   chown ec2-user:ec2-user /mnt/efs
   chmod 777 /mnt/efs
   

9. When executing docker run (as explained here), use -v to bind the mounted directory to /opt/datalogics/public. For example:

# Run the pdfRest Self-Hosted API server so that processed documents
# are deleted in 30 minutes. Files are permitted to process for
# a maximum of 60 minutes.
# Mount the EFS volume to /opt/datalogics/public.

docker run -d -p 80:3000 --restart always \
-e REMOVE_ORIGINAL_PROCESSED=1 \
-e MAX_PROCESS_TIME=3600 \
-v /mnt/efs:/opt/datalogics/public \
pdf_toolkit_self-hosted_api:latest

Mount Shared EFS

These steps will help you set up your pdfRest Self-Hosted API deployment to share an EFS volume between different Self-Hosted API products. This allows you chain API calls between various pdfRest products.

You can run the following commands to configure the mount for Docker. EFS_DNS_NAME is the name of your EFS volume.

sudo mkdir -p /mnt/efs
echo "EFS_DNS_NAME:/ /mnt/efs nfs4 _netdev 0 0" | sudo tee \
-a /etc/fstab
sudo mount -t nfs4 -o \
nfsvers=4.1,rsize=1048576,wsize=1048576,hard,timeo=600,retrans=2,noresvport \
EFS_DNS_NAME:/ /mnt/efs
chown ec2-user:ec2-user /mnt/efs
chmod 777 /mnt/efs
sudo systemctl restart docker

Finally, add the following command to the docker run command you configured above:

-v /mnt/efs:/opt/datalogics/public

Manually Load Balancing AMIs

Follow these instructions to manually set up a Load Balancer and Autoscaling Group for your Self-Hosted API. While we provide instructions for manually setting this up, this is best deployed as part of a CloudFormation stack.

1. Create a new AMI Snapshot from the EC2 dashboard.
2. Create a new Launch Template.
3. Create a new Target Group.
4. Create a new Autoscaling Group.
5. Add an Application Load Balancer to your Autoscaling Group.
6. Create new Listener Rules on the ALB.
7. Create new HTTPS Listener Rules on the ALB.
8. Create new Security Group Rules to properly secure your ALB.