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 30 minutes


Before you launch the solution's AWS CloudFormation template, you must specify an Amazon Simple Storage Service (Amazon S3) bucket in the SourceBuckets template parameter. Use this bucket to store the images you want to manipulate. Note that if you have multiple image source buckets, you can specify them as comma-separated values. 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 B.

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: CorsEnabled, CorsOrigins, SourceBuckets, DeployDemoUI, LogRetentionPeriod

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

Step 2. Create and Use Image Requests

  • Set up an image request on the front-end.

  • Send an image request to your API.

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.

  3. On the Create stack page, verify that the correct template URL shows in the Amazon S3 URL text box and choose Next.

  4. On the Specify stack details page, assign a name to your solution stack.

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

    Parameter Default Description
    CorsEnabled No Choose whether to enable Cross-Origin Resource Sharing (CORS).
    CorsOrigin * 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.


    This value is ignored if the CorsEnabled parameter is set to No.

    SourceBuckets <Requires input> The S3 bucket (or buckets) in your account that contains the images that you will manipulate. If providing multiple buckets, separate them by commas.
    DeployDemoUI Yes The demo UI that will be deployed to the Demo S3 bucket. For more information see Appendix B.
    LogRetentionPeriod 1 Number of days to retain Lambda log data in CloudWatch logs.
  6. Choose Next.

  7. On the Configure stack options page, choose Next.

  8. 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.

  9. Choose Create stack 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 30 minutes.

Step 2. Create and Use Image Requests

This solution generates a CloudFront domain name that gives you access to both original and modified images via the image handler API. The domain name is found in the Outputs section of the CloudFormation template as an ApiEndpoint. Parameters such as the image’s location and edits to be made are specified in a JSON object on the front-end.

For example, the following code block specifies the image location as myImageBucket and specifies edits of grayscale: true to change the image to grayscale.

const imageRequest = JSON.stringify({ bucket: “myImageBucket” key: “myImage.jpg”, edits: { grayscale: true } })

Use the following procedure to create image requests:

  1. In the AWS CloudFormation Management Console, choose the Outputs tab and make a note of the URL that appears next to ApiEndpoint. This URL is the endpoint URL for your newly provisioned image handler API.

  2. In a code sandbox, or in your front-end application, create a new JSON object. This object will contain the key-value pairs needed to successfully retrieve and perform edits on your images.

  3. Using the code sample above and the Sharp documentation, adjust the following properties to meet your image editing requirements.

    • Bucket – Specify the Amazon S3 bucket containing your original image file. This is the name specified in the SourceBuckets template parameter. You can update the image location by adding it into the SOURCE_BUCKETS environment variable of your image handler AWS Lambda function.

    • Key – Specify the filename of your original image. This name should include the file extension as well as any subfolders between its location and the root of the bucket. For example, folder1/folder2/image.jpg.

    • Edits – Specify any image edits as key-value pairs. If you do not specify image edits, the original image will be returned with no changes made.

  4. Stringify and encode your image request. You can use JavaScript’s JSON.stringify() property, followed by encoding the result using the btoa() property.

  5. Append the encoded result to your ApiEndpoint URL and use this as the value for the HTML img src property or in a GET request. See the following example.

    const imageRequest = JSON.stringify({ bucket: “myImageBucket” key: “myImage.jpg”, edits: { grayscale: true } }); const url = `${CloudFrontUrl}/${btoa(imageRequest)}`; // Alternatively, you can call the url directly in an <img> element, similar to: <img src=`${url}` />

    The following is an example of the preceding code results in an encoded image request: