Serverless Image Handler
Serverless Image Handler

Automated Deployment

Follow the step-by-step instructions in this section to configure and deploy the Serverless Image Handler into your account.

Time to deploy: Approximately 25 minutes


Before you launch the solution's AWS CloudFormation template, you must specify an existing Amazon Simple Storage Service (Amazon S3) bucket. Use this bucket to store the images you want to manipulate. For lower latency, use an S3 bucket in the same AWS Region where you launch your AWS CloudFormation template.

We recommend deploying the optional demo user interface when you first deploy the solution to test the solution’s functionality. For more information, see Appendix A.

What We'll Cover

The procedure for deploying this architecture on AWS consists of the following steps. For detailed instructions, follow the links for each step.

Step 1. Launch the Stack

  • Launch the AWS CloudFormation template into your AWS account.

  • Enter values for required parameters: Origin S3 Bucket, Origin S3 Bucket Region, UI Prefix

  • Review the other template parameters, and adjust if necessary.

Step 2. Create an Image URL

  • Generate URLs for your images.

Step 1. Launch the Stack

This automated AWS CloudFormation template deploys the Serverless Image Handler on the AWS Cloud.


You are responsible for the cost of the AWS services used while running this solution. See the Cost section for more details. For full details, see the pricing webpage for each AWS service you will be using in this solution.

  1. Log in to the AWS Management Console and click the button below to launch the serverless-image-handler AWS CloudFormation template.

                                Serverless Image Handler launch button

    You can also download the template as a starting point for your own implementation.

  2. The template is launched in the US East (N. Virginia) Region by default. To launch the Serverless Image Handler in a different AWS Region, use the region selector in the console navigation bar.


    This solution uses the AWS Lambda and Amazon API Gateway services, which are currently available in specific AWS Regions only. Therefore, you must launch this solution an AWS Region where Lambda and API Gateway are available. For the most current service availability by region, see AWS service offerings by region.

  3. On the Select Template page, keep the default settings for the Stack and Template Source.

  4. Under Parameters, review the parameters for the template and modify them as necessary. This solution uses the following default values.

    Parameter Default Description
    Origin S3 Bucket <Requires input> The S3 bucket that contains the images that you will manipulate
    Origin S3 Bucket Region us-east-1 The region that contains the Origin S3 Bucket
    Enable CORS No Will this API require Cross-Origin Resource Sharing (CORS) support?
    CORS Origin * This value will be returned by the API in the Access-Control-Allow-Origin header. A star (*) value will support any origin. We recommend specifying a specific origin (e.g. http://example.domain) to restrict cross-site access to your API.
    Lambda Log Retention 1 Number of days to retain Lambda log data in CloudWatch logs
    Deploy UI Yes The demo UI that will be deployed to the Demo S3 bucket. For more information see Appendix A.
    UI Prefix serverless-image-handler-ui/ The prefix for the files in the Origin S3 bucket. Note that only one folder can be used.
  5. Choose Next.

  6. On the Options page, choose Next.

  7. On the Review page, review and confirm the settings. Be sure to check the box acknowledging that the template will create AWS Identity and Access Management (IAM) resources.

  8. Choose Create to deploy the stack.

    You can view the status of the stack in the AWS CloudFormation console in the Status column. You should see a status of CREATE_COMPLETE in approximately 25 minutes.

Step 2. Create an Image URL

This solution generates a CloudFront domain name that gives you access to the images in your S3 bucket, as well as a partial URL, you can use to manipulate images. Note that you must set the Deploy UI template parameter to No to generate the partial URL (SampleRequest URL).

  1. In the AWS CloudFormation stack Outputs tab, copy the Sample Request URL.

  2. Paste the URL into your browser and append it with a Thumbor filter, the path (if applicable), and filename for an image in your S3 bucket.


    If the image name and extension in the URL doesn’t match the image name in the S3 bucket, you will receive an error.

In your custom front-end application, you can append the CloudFront URL with the bucket folder path and image name to create a URL for each image object (example: http://cloudfront…/path/image01.jpg).


If you choose to deploy the optional demo user interface, you can experiment with all of the supported image manipulation features, preview the results, and create example URLs that you can use for your other images. For more information, see Appendix A.