Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/gekorm/aws-sih

AWS solution to dynamically edit images on the fly with SharpJS
https://github.com/gekorm/aws-sih

aws-cdk image-compression image-processing lambda optimize-images responsive-images sharp

Last synced: 18 days ago
JSON representation

AWS solution to dynamically edit images on the fly with SharpJS

Host: GitHub
URL: https://github.com/gekorm/aws-sih
Owner: GeKorm
License: apache-2.0
Created: 2023-02-26T15:02:08.000Z (almost 2 years ago)
Default Branch: main
Last Pushed: 2024-08-15T08:56:47.000Z (5 months ago)
Last Synced: 2024-12-06T21:36:54.101Z (28 days ago)
Topics: aws-cdk, image-compression, image-processing, lambda, optimize-images, responsive-images, sharp
Language: TypeScript
Homepage:
Size: 8.1 MB
Stars: 0
Watchers: 1
Forks: 1
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS

Awesome Lists containing this project

README

**Fork of [Serverless Image Handler](https://aws.amazon.com/solutions/implementations/serverless-image-handler/)**

## Table of Contents

- [Changes in this fork](#changes-in-this-fork)
- [Deploying or Customizing the Solution](#deploying-or-customizing-the-solution)
- [Prerequisites](#prerequisites)
- [1. Clone the repository](#1-clone-the-repository)
- [2. Unit Test](#2-unit-test)
- [3. Build and Deploy](#3-build-and-deploy)
- [Default generated cloudfront domain](#default-generated-cloudfront-domain)
- [Custom domains](#custom-domains)
- [Automated deployments](#automated-deployments)
- [Usage](#usage)
- [Basic example](#basic-example)
- [Other examples](#other-examples)
- [**Query parameters**](#query-parameters)
- [Thumbor and Rewrites](#thumbor-and-rewrites)
- [**Configuration reference**](#configuration-reference)
- [Cloudformation](#cloudformation)
- [Context](#context)
- [Environment variables](#environment-variables)
- [License](#license)

# Changes in this fork

- **New URL scheme**. Edit with Sharp using search (query) parameters for better SEO. See [Usage](#usage)
- **Custom domain**. A certificate and hosted zone is automatically generated for your domain
- Improved cache hit ratio when `AutoWebPParameter` is enabled
- Origin Shield support for improved cache hit ratio and performance
- Disabled data collection
- Upgraded dependencies
- Improved cross-region support
- Scripts are only run from local dependencies (uses `npm run` instead of `npx`) for greater reliability

## Deploying or Customizing the Solution

### Prerequisites

- [AWS Command Line Interface](https://aws.amazon.com/cli/)
- Node.js 20.x or later

### 1. Clone the repository

```bash
git clone https://github.com/GeKorm/aws-sih.git
cd aws-sih
export MAIN_DIRECTORY=$PWD
```

### 2. Unit Test

After making changes, run unit tests to make sure added customization passes the tests:

```bash
cd $MAIN_DIRECTORY/deployment
chmod +x run-unit-tests.sh && ./run-unit-tests.sh
```

### 3. Build and Deploy

Pick either

- [Default generated cloudfront domain](#default-generated-cloudfront-domain)
- [Custom domains](#custom-domains)

#### Default generated cloudfront domain

```bash
cd $MAIN_DIRECTORY/source/constructs
npm run clean:install
overrideWarningsEnabled=false npm run cdk -- bootstrap --profile
overrideWarningsEnabled=false npm run cdk -- deploy\
--parameters DeployDemoUIParameter=No\
--parameters SourceBucketsParameter=\
--profile
```

#### Custom domains

```bash
cd $MAIN_DIRECTORY/source/constructs
npm run clean:install
overrideWarningsEnabled=false npm run cdk -- bootstrap --profile
overrideWarningsEnabled=false npm run cdk -- deploy --all\
--parameters ServerlessImageHandlerStack:DeployDemoUIParameter=No\
--parameters ServerlessImageHandlerStack:SourceBucketsParameter=\
--context customDomain=\
--profile
```

The first deployment with a custom domain requires verifying ownership, if not already verified. Until verified, the **deployment will seem stuck** at the `Certificate create_in_progress` step. Please see `https://docs.aws.amazon.com/acm/latest/userguide/domain-ownership-validation.html` for instructions. The solution will have created a Hosted zone for you custom domain, which you can view in the AWS Route 53 dashboard.

_Note:_

- **MY_BUCKET**: name of an existing bucket or buckets in your account
- **PROFILE_NAME**: name of an AWS CLI profile that has appropriate credentials for deploying in your preferred region
- **MY_DOMAIN**: full domain to use as a Cloudfront alias, eg `--context customDomain=x.example.com`

See all parameters: [Parameters reference](#parameters-reference)

#### Automated deployments

For automated deployments with GitHub actions, see `.github/workflows/pipeline-workflow.yml`.

1. Fork this repo
2. Bootstrap locally if not already done
3. Change `if: github.repository_owner == 'GeKorm'` to your user or organization name
4. Add the following variables and secrets:
- Secret **DISPATCHER_ROLE_ARN** (for [`role-to-assume` in aws credentials action](https://github.com/aws-actions/configure-aws-credentials))
- Secret **SOURCE_BUCKETS** (for [`SourceBucketsParameter`](#cloudformation))
- _[Optional]_ Variable **DEMO_UI** (for [`DeployDemoUIParameter`](#cloudformation))
- _[Optional]_ Secret **CUSTOM_DOMAIN** (for [`customDomain`](#context))
- _[Optional]_ Secret **AWS_REGION** ([environment variable](#environment-variables))

For further customization, such as using Origin Shield, please modify the pipeline workflow command.

## Usage

The new URL scheme is `https:///?edits=`. The bucket and key are part of the URL unencoded. All other parameters like moved to the query string portion of the URL.

### Basic example

```typescript
// How to use edits https://docs.aws.amazon.com/solutions/latest/serverless-image-handler/create-and-use-image-requests.html#dynamically-resize-photos
const edits = {};

// Stringify and encode URI
// For s3 bucket "bucket" and image key "/folder/image.jpg":
const url = `https://example.cloudfront.net/bucket/folder/image.jpg?edits=${encodeURIComponent(
JSON.stringify(edits),
)}`;
```

#### Other examples

The image's full S3 URL can be used. This is a non-exhaustive list of accepted formats

- https://example.cloudfront.net/bucket/folder/image.jpg?edits=
- https://example.cloudfront.net/s3.us-east-1.amazonaws.com/bucket/test.jpg?edits=
- https://example.cloudfront.net/https://s3.amazonaws.com/bucket/test?edits= (extension is optional)
- https://example.cloudfront.net/s3.amazonaws.com/bucket/test.jpg?edits=
- https://example.cloudfront.net/https://s3-us-east-1.amazonaws.com/source-bucket/test.jpg?edits=

Please open an issue if your preferred S3 URL format isn't supported.

### Query parameters

| Key | Value |
| -------------- | ------------------------------------------------------------------------------------------------- |
| `signature` | `string` |
| `effort` | `number` (Default: `4`, see [Sharp `options.effort`](https://sharp.pixelplumbing.com/api-output)) |
| `outputFormat` | [`ImageFormatTypes`](source/image-handler/lib/enums.ts#L19) |
| `edits` | `encodeURIComponent(JSON.stringify(edits))` |
| `headers` | `encodeURIComponent(JSON.stringify(headers))` |

As an alternative to `encodeURIComponent` you can use `URL` or `URLSearchParams`

```typescript
const url = new URL("https://cdn.example.com/bucket/image.jpg");
url.searchParams.set("outputFormat", "webp");
url.searchParams.set("edits", JSON.stringify(edits));

console.log(url.toString());
// https://cdn.example.com/bucket/image.jpg?outputFormat=webp&edits=%7B%22

// or equivalent
const params = new URLSearchParams();
params.set("outputFormat", "webp");
params.set("edits", JSON.stringify(edits));

console.log("https://cdn.example.com/bucket/image.jpg?" + params.toString());
// https://cdn.example.com/bucket/image.jpg?outputFormat=webp&edits=%7B%22
```

### Thumbor and Rewrites

Thumbor and the Rewrite feature may work, but are not supported. Please use the [original solution](https://github.com/aws-solutions/serverless-image-handler) if required.

## Configuration reference

Required in **bold**

### Cloudformation

#### `--parameters` flag

These parameters can be added using the `--parameters ServerlessImageHandlerStack:` command line flag.

| Name | Type | Default |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| CorsEnabledParameter

Would you like to enable Cross-Origin Resource Sharing (CORS) for the image handler API? Select 'Yes' if so.

| String

YesNo | `No` |
| CorsOriginParameter

If you selected 'Yes' above, please specify an origin value here. A wildcard (\*) value will support any origin. We recommend specifying an origin (i.e. https://example.domain) to restrict cross-site access to your API.

| String | `*` |
| SourceBucketsParameter

(Required) List the buckets (comma-separated) within your account that contain original image files. If you plan to use Thumbor or Custom image requests with this solution, the source bucket for those requests will be the first bucket listed in this field.

| String | `defaultBucket, bucketNo2, bucketNo3, ...` |
| DeployDemoUIParameter

Would you like to deploy a demo UI to explore the features and capabilities of this solution? This will create an additional Amazon S3 bucket and Amazon CloudFront distribution in your account. NOTE: The demo UI doesn't work with this fork, select "No".

| String

YesNo | `Yes` |
| LogRetentionPeriodParameter

This solution automatically logs events to Amazon CloudWatch. Select the amount of time for CloudWatch logs from this solution to be retained (in days).

| Number

13571430609012015018036540054573118273653 | `1` |
| AutoWebPParameter

Would you like to enable automatic WebP based on accept headers? Select 'Yes' if so.

| String

YesNo | `No` |
| EnableSignatureParameter

Would you like to enable the signature? If so, select 'Yes' and provide SecretsManagerSecret and SecretsManagerKey values.

| String

YesNo | `No` |
| SecretsManagerSecretParameter

The name of AWS Secrets Manager secret. You need to create your secret under this name.

| String | `` |
| SecretsManagerKeyParameter

The name of AWS Secrets Manager secret key. You need to create secret key with this key name. The secret value would be used to check signature.

| String | `` |
| EnableDefaultFallbackImageParameter

Would you like to enable the default fallback image? If so, select 'Yes' and provide FallbackImageS3Bucket and FallbackImageS3Key values.

| String

YesNo | `No` |
| FallbackImageS3BucketParameter

The name of the Amazon S3 bucket which contains the default fallback image. e.g. my-fallback-image-bucket

| String | `` |
| FallbackImageS3KeyParameter

The name of the default fallback image object key including prefix. e.g. prefix/image.jpg

| String | `` |
| CloudFrontPriceClassParameter

The AWS CloudFront price class to use. For more information see: [Cloudfront documentation](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/PriceClass.html)

| String

PriceClass_AllPriceClass_200PriceClass_100 | `PriceClass_All` |

### Context

#### `source/constructs/cdk.json`

These parameters can be added under `context` in `cdk.json`, or using the `--context` command line flag.

Alternative domain name for this distribution. For more information, see [Cloudfront documentation](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_cloudfront.Distribution.html#domainnames)

| String | `` |
| originShieldEnabled

Enable Origin Shield to improve cache hit ratio and performance. For more information, see [Origin Shield documentation](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/origin-shield.html)

| String

YesNo | `No` |
| originShieldRegion

Must be specified if Origin Shield is not supported in your [AWS_REGION](#environment-variables). See [Origin Shield regions](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/origin-shield.html#choose-origin-shield-region)

| String | `process.env.AWS_REGION` |

### Environment variables

Deploy the solution to this region. [Supported regions](https://docs.aws.amazon.com/solutions/latest/serverless-image-handler/supported-aws-regions.html)

| String | `us-east-1` |

## License