diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..95cdd77 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,21 @@ +# Introduction + +## What is Serverless Sharp? +Serverless Sharp is a self-hosted image processing solution that uses [Sharp](https://sharp.pixelplumbing.com/) by + Pixel Plumbing. Serverless Sharp requires no database, no server, and no additional services beyond those offered by + AWS. + +## Who is this for? +This software is for people who want to optimize and run basic transformations (crop, scale, convert, etc) on images + from an existing S3 bucket without running computationally expensive processes or servers or paying for expensive + third-party services. + +## How does it work? +After deploying this solution, you'll find yourself with a number of AWS resources (all priced based on usage rather +than monthly cost). The most important of which are: +- **AWS Lambda**: Pulls images from your S3 bucket, runs the transforms, and outputs the image from memory +- **API Gateway**: Acts as a public gateway for requests to your Lambda function +- **Cloudfront Distribution**: Caches the responses from your API Gateway so the Lambda function doesn't re-execute + +Once deployed, a Cloudfront distribution is generated that is directed to the generated API Gateway. This distribution +ensures the Lambda function does not get run multiple times for the same image request. diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..79f6929 --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,133 @@ +# Configuration +Serverless Sharp stores its settings in YAML files. When deploying the application, you specify the YAML file and the +stage (your environment). For example: + +```sh +serverless deploy --settings mysite.com.yml --stage prod +``` + +## Settings File Structure +We use YML files to make use of their inheritance. This allows us to define some defaults and then branch environment +-specific changes off of them. For example: + + +```yml +defaults: &defaults + serviceName: image-handler-test + offlinePort: 80 + region: 'us-east-1' + environment: &defaults.environment + DEFAULT_QUALITY: 75 + DEFAULT_COMPRESS_QUALITY: 45 + SLS_IGNORE: favicon.ico + SLS_VALID_PATH_REGEX: '.*' + MAX_IMAGE_WIDTH: 2000 + MAX_IMAGE_HEIGHT: 1000 + PNGQUANT_SPEED: 10 + DEFAULT_CACHE_CONTROL: 'max-age=2592000' + +stages: + dev: + <<: *defaults + environment: + <<: *defaults.environment + SOURCE_BUCKET: 'my-bucket/prefix/path' + SECURITY_KEY: '' + CUSTOM_DOMAIN: '' + prod: + <<: *defaults + environment: + <<: *defaults.environment + SOURCE_BUCKET: 'random-string-here' + SECURITY_KEY: '' + CUSTOM_DOMAIN: 'my.domain.com' + +``` + +## Environment Settings +The majority of the application and environment specific settings are configured as environment variables that are + passed into the Lambda service handler. + + ### `DEFAULT_QUALITY` + + - Type: `integer` + - Default: `75` + + A number between 1 and 100 representing the default image quality. + +### `DEFAULT_COMPRESS_QUALITY` + +- Type: `integer` +- Default: `75` + +A number between 1 and 100 for the default quality when an image is requested to be compressed + +### `SLS_IGNORE` + +- Type: `string` +- Default: `` + +A comma-delineated string of paths that should be ignored (for example, `favicon.ico`) + +### `SLS_VALID_PATH_REGEX` + +- Type: `Regular Expression` +- Default: `.*` + +A regular expression for path validation. Allows you to explicitly control what assets may be handled by the Lambda + function. If the request path fails this test, a 404 response will be served. + +Example: +```yaml +# All requests must start with /images/ +SLS_VALID_PATH_REGEX: ^\/images\/.*` +``` + +### `MAX_IMAGE_WIDTH` + +- Type: `integer` +- Default: `2000` + +Images may not be requested with a width larger than this value + +### `MAX_IMAGE_HEIGHT` + +- Type: `integer` +- Default: `2000` + +Images may not be requested with a height larger than this value + +### `PNGQUANT_SPEED` + +- Type: `integer` +- Default: `10` + +The speed value to pass to the `pngquant` optimization program. From the [pngquant website](https://pngquant.org/): + +> Speed/quality trade-off from 1 (brute-force) to 10 (fastest). The default is 3. Speed 10 has 5% lower quality, but is 8 times faster than the default. + +### `DEFAULT_CACHE_CONTROL` + +- Type: `string` +- Default: `` + +By default, Serverless Sharp will serve responses with the same Cache-Control header as the object being served. If + the Cache-Control header is not set, this value will be used. + + +### `SOURCE_BUCKET` + +- Type: `string` +- Default: `` + +### `SECURITY_KEY` + +- Type: `string` +- Default: `` + +### `CUSTOM_DOMAIN` + +- Type: `string` +- Default: `` + +> **NOTE:** This requires deployment in the `us-east-1` region! diff --git a/docs/deployment.md b/docs/deployment.md new file mode 100644 index 0000000..d36c65e --- /dev/null +++ b/docs/deployment.md @@ -0,0 +1 @@ +# Deployment diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..8597e64 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,48 @@ + + + + + + Serverless Sharp + + + +
+ + + + diff --git a/docs/usage/integration.md b/docs/usage/integration.md new file mode 100644 index 0000000..50a133c --- /dev/null +++ b/docs/usage/integration.md @@ -0,0 +1 @@ +# Integration diff --git a/docs/usage/parameters.md b/docs/usage/parameters.md new file mode 100644 index 0000000..04f9547 --- /dev/null +++ b/docs/usage/parameters.md @@ -0,0 +1 @@ +# Parameters diff --git a/docs/usage/security.md b/docs/usage/security.md new file mode 100644 index 0000000..8dbb2f9 --- /dev/null +++ b/docs/usage/security.md @@ -0,0 +1 @@ +# Security diff --git a/package.json b/package.json index f2f0c9c..78d5b20 100644 --- a/package.json +++ b/package.json @@ -7,7 +7,8 @@ "email": "info@venveo.com" }, "scripts": { - "test": "jest" + "test": "jest", + "docs": "serve ./docs" }, "version": "1.0.0", "private": false, diff --git a/src/helpers/settings.js b/src/helpers/settings.js index 37443ae..197f932 100644 --- a/src/helpers/settings.js +++ b/src/helpers/settings.js @@ -11,7 +11,7 @@ const settings = { type: TYPE_INTEGER }, DEFAULT_COMPRESS_QUALITY: { - default: 45, + default: 75, type: TYPE_INTEGER }, SLS_IGNORE: {