Deploy on AWS
Learn how to set up and deploy your pdfRest Self-Hosted API on AWS.
Self-Hosted API on AWS
Host the pdfRest API on your own AWS VPC, with full control for scaling and security.
Deployment Options
The pdfRest Self-Hosted API products available on the AWS Marketplace offer two methods of deployment, an AMI (Amazon Machine Image) and a CloudFormation Template. The first part of this guide covers the CloudFormation Template deployment.
All Self-Hosted API products share the same deployment and configuration guides.
You can access your AWS Marketplace subscriptions from:
- Select the product page of the product you have Subscribed to.
- Select "View Purchase Options"
- Select "Continue to Configuration"
- Under the "Fulfillment option" dropdown, select either "Amazon Machine Image" or "CloudFormation Template".
AWS CloudFormation
The CloudFormation Template automates the deployment of one or more pdfRest EC2 instances alongside optional support infrastructure.
The CloudFormation Template is highly recommended for users who prefer an automated, pre-configured solution. The AMI deployment requires technical experience with AWS networking and compute services.
The CloudFormation Template automates the deployment of highly-scalable infrastructure, suitable for any usage scenario from small business to enterprise-scale.
Deploy with CloudFormation
Version and Region
After selecting the CloudFormation Template under "Fulfillment options", you'll see three new dropdowns:
- Select
API Stack with Load Balancer and Auto Scaling - Select the latest
Software version - Choose which
Regionyou intend to deploy the pdfRest Self-Hosted API into.
On the next page, select "Launch CloudFormation" under the "Choose Action" dropdown, then "Launch".
The CloudFormation Console
'Step 1, Create stack' - Leave all settings default and click "Next".
'Step 2, Specify stack details' - Enter a name for the stack, such as: pdfRest-Self-Hosted-API-Production
Fill out the Parameters down the page as needed.
- Parameters marked as
(REQUIRED)are mandatory fields are need either the default value or a custom value in their field. - Parameters marked as
(Optional)include information about their purpose. Most will have a default value or can be left blank.
See the Environment Variables section of the Configuration guide for detailed information about Optional Parameters.
'Step 3, Configure stack options' - All of these settings are optional, based on your organization's CloudFormation and tagging policies.
'Step 4, Review and create' - Review all of configuration choices made in the previous 3 sections. When you've confirmed your choices, click "Submit".
Stack Creation
- 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
CREATE_IN_PROGRESS. Click on the Stack name for additional information. - When the pdfRest Self-Hosted API is finished building, the Stack status will be
CREATE_COMPLETE.
Additional information about CloudFormation stack progress and more can be found in the AWS CloudFormation documentation.
CloudFormation FAQ
Below is a list of important and commonly asked questions related to deploying pdfRest Self-Hosted API using AWS CloudFormation.
How does the CloudFormation Stack work?
- All calls enter through an Internet Gateway in front of an Application Load Balancer.
- The load balancer will distribute traffic to a Target Group containing EC2 instances that are defined and initialized by the stack's Launch Template, and are grouped by an Auto Scaling Group.
- All instances created by this group will use the same shared Elastic File System volume, so any file can be processed by any instance.
Which CloudFormation Template parameters must be filled out?
- The only CFN parameters that are empty and must be filled in prior to using the product are "Stack name" and "Key Pair for SSH".
- You must also change the "IP Address Range for HTTP and HTTPS" parameter to your IP address, or you will not be able to make calls to the instances. 0.0.0.0/0 will allow all IP addresses.
- A stack resource label is required, and should be unique for every stack - however the prefilled value will work fine for your first stack.
- We suggest also changing "IP Address Range for SSH" to your IP address - otherwise you will not be able to SSH onto the EC2 instances.
Do I need to fill in the empty optional parameters?
- No. If these are left blank, CloudFormation will generate the appropriate resources per the template's instructions.
- Existing resources can be used by filling in the relevent CloudFormation parameters.
Amazon Machine Image (AMI)
The pdfRest Self-Hosted API products available on the AWS Marketplace offer two methods of deployment, an AMI (Amazon Machine Image) and a CloudFormation Template. The following section covers the AMI deployment.
Users not familiar with AWS networking and compute services are advised to use the CloudFormation template, which automates most of the following procedures.
The pdfRest PDF Toolkit Self-Hosted API product is provided as an Amazon Machine Image (AMI). This AMI is a snapshot of a server configuration and is available on the AWS Marketplace. It can be used as a template to deploy your own server instance, allowing you to add our PDF processing features to your own AWS environment or build your own custom workflows that you can run on demand.
The Amazon Machine Image allows you to deploy a single EC2 instance without any optional infrastructure components. This is ideal for small scale processing, batch processing, or other uses that don't require a load balancer or multiple machines. Deeper knowledge of AWS infrastructure setup and configuration is recommended for direct AMI deployments.
Deploy an EC2 with the AMI
For this process you will need to have already subscribed to the pdfRest Self-Hosted API product on the AWS Marketplace.
Access the EC2 console by logging into the AWS Management Console and searching for EC2.
Select Launch Instance from the EC2 Dashboard. This can also be found at the top right the “Instances” view.
Enter a name for your instance.
Under Application and OS Images (Amazon Machine Image) select “Browse more AMIs”.
Search for pdfRest under AWS Marketplace AMIs and select pdfRest PDF Toolkit Self-Hosted API. A popup view will appear that will allow you to review the product. Once you’ve finished reading, to continue forward select Continue.
For Instance Type, we recommend a c7i.xlarge for normal usage.
Select a key pair to use with this instance. If you do not have one, follow the link to create one. Ensure that you keep the private key. AWS has documentation on creating a key pair that can be found here.
Select a security group to use with this instance. If you do not have one then you can create one at this time. For the purposes of this guide, we’ll use our default security group. AWS’ documentation on EC2 security groups can be found here.
Configure your storage volume. For our purposes we’ll use a 100 GiB gp3 volume. Note that the volume must be at least 100 GiB.
You can then launch the instance. You should see a confirmation message such as this one, with the ID of the new instance. Clicking on the link will take you to your instances list, where you can find further details.
