Automated deployment - 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 15 minutes


Before you launch the solution's AWS CloudFormation template, you must specify an Amazon Simple Storage Service (Amazon S3) bucket in the Source Buckets template parameter. Use this S3 bucket to store the images you want to manipulate. If you have multiple image source S3 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.


If you are launching from Hong Kong (ap-east-1), Bahrain (me-south-1), Cape Town (af-south-1), or Milan (eu-south-1) Region, the source S3 bucket you created and provided as the Source Buckets template parameter must be in the same Region where you are launching the 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, refer to Using the demo UI.

Deployment overview


Serverless Image Handler v6.0 includes breaking changes and cannot be updated from previous versions. To use version 6.0, you must launch a new stack using version 6.0 of the AWS CloudFormation template. You can uninstall your previous version of this solution.

Deploying this architecture on AWS includes 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: CORS Enabled, CORS Origin, Source Buckets, Deploy Demo UI, Log Retention Period, Enable Signature, Enable Default Fallback Image, AutoWebP, and CloudFront PriceClass.

  • 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 solution in the AWS Cloud.


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

  1. Log in to the AWS Management Console and select the button 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
    CORS Enabled No Choose whether to activate Cross-Origin Resource Sharing (CORS). For information about this parameter, refer to Cross-Origin Resource Sharing.
    CORS Origin * This value is returned by the API in the Access-Control-Allow-Origin header. An asterisk (*) value supports 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 CORS Enabled parameter is set to No.

    Source Buckets <Requires input> Specifies the S3 bucket (or buckets) in your account that contains the images that you manipulate. To specify multiple buckets, separate them by commas.
    Deploy Demo UI Yes The demo UI that deploys to the Demo S3 bucket. For more information refer to Using the demo UI.
    Log Retention Period 1 Specifies the number of days to retain Lambda log data in CloudWatch logs.
    Enable Signature No Choose whether to activate the image URL signature feature. For information about this feature, refer to Image URL signature.
    SecretsManager Secret <Optional input> Define the AWS Secrets Manager secret name that contains the secret key for the image URL signature.

    This value is ignored if the Enable Signature parameter is set to No.

    SecretsManager Key <Optional input> Define the AWS Secrets Manager secret key that contains the secret value to create the image URL signature.

    This value is ignored if the Enable Signature parameter is set to No.

    Enable Default Fallback Image No Choose whether to activate the default fallback image feature. For information about this feature, refer to Default fallback image.
    Fallback Image S3 Bucket <Optional input> Specify the Amazon S3 bucket which contains the default fallback image.

    This value is ignored if the Enable Default Fallback Image parameter is set to No.

    Fallback Image S3 Key <Optional input> Specify the default fallback image Amazon S3 object key including prefix.

    This value is ignored if the Enable Default Fallback Image parameter is set to No.

    AutoWebP No Choose whether to automatically accept webp image formats.
    CloudFront PriceClass PriceClass All The AWS CloudFront price class to use. For more information refer to Choosing the price class for a CloudFront distribution.
  6. Choose Next.

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

  8. On the Review page, review and confirm the settings. Check the box acknowledging that the template creates 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 receive a CREATE_COMPLETE status in approximately 15 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 contains 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 that is 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 returns 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. Refer to 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:


For information regarding how to use additional features in an image request, refer to Smart cropping, Round cropping, and Content moderation. For additional features supported by Sharp, refer to the Sharp documentation.