🏙 Retinal is a Serverless AWS Lambda service for resizing images on-demand or event-triggered
Serverless Framework-based AWS Lambda function triggered by S3 events to resize images with the excellent Sharp module. By using the Sharp module (which uses the libvips library), image processing can be 3x-5x faster than using ImageMagick, thus reducing the time your function spends running, which can potentially dramatically decrease your lambda function's cost. The function's behaviour can be controlled entirely with configuration.
A tool to take images uploaded to an S3 bucket and produce one or more images of varying sizes, optimizations and other operations all controlled from a simple configuration file. It does this by creating an AWS Lambda function with the help of the Serverless Framework.
Please note, currently the master branch is broken, please use v0.11.0 instead. See comment.
Installation can be achieved with the following commands
git clone https://github.com/adieuadieu/serverless-sharp-image
cd serverless-sharp-image
yarn install
(It is possible to exchange yarn
for npm
if yarn
is too hipster for your taste. No problem.)
Or, if you have serverless
installed globally:
serverless install -u https://github.com/adieuadieu/serverless-sharp-image
Then, modify the config.js
and event.json
files, adapting them to your needs. More on configuration below.
You must configure your AWS credentials either by defining AWS_ACCESS_KEY_ID
and AWS_SECRET_ACCESS_KEY
environmental variables, or using an AWS profile. You can read more about this on the Serverless Credentials Guide. It's a bit of a pain in the ass if you have many projects/credentials.
In short, either:
export AWS_PROFILE=<your-profile-name>
or
export AWS_ACCESS_KEY_ID=<your-key-here>
export AWS_SECRET_ACCESS_KEY=<your-secret-key-here>
Make sure the bucket in config.js
exists.
Then:
yarn test
You can also try out the service by invoking it. First deploy it with yarn run deploy
and then you can invoke your function with yarn run invoke
. This will invoke the function with the test event in event.json
. You may need to tweak this file to match your setup.
serverless deploy -v
This package bundles a lambda-execution-environment-ready version of the Sharp library which allows you to deploy the lambda function from any OS.
The lambda service is designed to be controlled by configuration. From the configuration you can setup how one or more images will be manipulated, with direct access to the underlying methods of Sharp for full control.
module.exports = {
name: 'serverless-sharp-image',
provider: {
profile: 'CH-CH-CH-CHANGEME',
stage: 'dev',
region: 'us-east-1',
},
sourceBucket: 'my-sweet-unicorn-media',
sourcePrefix: 'originals/',
destinationBucket: 'my-sweet-unicorn-media',
destinationPrefix: 'web-ready/',
all: [['rotate'], ['toFormat', 'jpeg', { quality: 80 }]],
outputs: [
{
key: '%(filename)s-200x200.jpg',
params: {
ACL: 'public-read',
},
operations: [['resize', 200, 200], ['max'], ['withoutEnlargement']],
},
{
key: '%(filename)s-100x100.jpg',
operations: [['resize', 100, 100], ['max'], ['withoutEnlargement']],
},
],
}
TODO: document configuration better/more detail
all - applied to the image before creating all the outputs
outputs - define the files you wish to generate from the source
sharp(image).resize(200, 300)
you would define this in your configuration as ["resize", 200, 300]
Note that method's are performed in order they appear in the configuration, and differing order can produce different results.key - The full object key with which the service was invoked
Example:
unicorns/and/pixie/sticks/omg.jpg
%(key)s
- "unicorns/and/pixie/sticks/omg.jpg"type - The Content-Type of the object, as returned by S3
Example:
image/jpeg
%(type)s
- "image/jpeg"crumbs - The crumbs of the S3 object as an array (e.g. the object key split by "/", not including the filename)
Example:
unicorns/and/pixie/sticks/omg.jpg
%(crumbs[0])s
- "unicorns"%(crumbs[2])s
- "pixie"directory - The "directory" of the S3 object
Example:
unicorns/and/pixie/sticks/omg.jpg
%(directory)s
- "unicorns/and/pixie/sticks"filename - The file name (minus the last extension)
Example:
unicorns/and/pixie/sticks/omg.jpg
%(filename)s
- "omg"extension - The file's extension determined by the Content-Type returned by S3
Example:
image/png
%(extension)s
- "png"Although not necessary (it's pre-packaged/included), if you'd like, you can build the sharp module native binaries for Lambda yourself with:
yarn build:sharp
This requires that you have Docker installed and running. More info here.
export AWS_CLIENT_TIMEOUT=3000000
See the CHANGELOG