Load, resize, cache, and generate (simple, single-letter) images.
- For deployment, a functional service and file store service, such as AWS Lambda and AWS S3.
- Functional service must run Node 8.10 or newer
- Once deployed, call the service at the setup HTTPS endpoint, with the following paths and parameters
- Image only:
/bucket_directory/filename.ext?width=300&height=300
- Letter only:
/any_directory/letter?width=300&height=300&primaryColor=%23ff0000ff&secondaryColor=%23ffd700ff
width
andheight
are standard pixel values- Aspect ratio of the source will be maintained; transparent areas will fill areas that grow to fill space to keep original aspect ratio will providing the requested size
- A square (1:1) aspect ratio is encouraged (for letter generation compatibility), but not required
- Densities are default 72dpi, so if you want high DPI double (triple, etc.) the requested size
- The resulting image will never have a side that is greater than the original image, or the generated letter raw size (currently set to 900x900); plan accordingly since the returned image may not be as big as requested, though the aspect ratio will still match the requested ratio
- For safety (to make sure developers are at least aware that width and height should be supplied), width and height are required
primaryColor
andsecondaryColor
should be hex values with a hash (#) prefix- do not forget to URL-escape the hash so the browser does not treat it like an anchor identifier (
#
=%23
; see the examples below) - must be in RGB or RGBA format (ie:
#00cc33
or#00cc33ff
) - default colors will be used if colors missing or could not be parsed
- if the requested image can not be loaded, and the letter parameters are supplied (with a
letter
parameter instead of in the path) then the system will fall back to returning the requested letter
- do not forget to URL-escape the hash so the browser does not treat it like an anchor identifier (
- Image only:
https://some.endpoint.com/my_s3_bucket/0123abcd.png?width=300&height=300
https://some.endpoint.com/my_s3_bucket/w?width=300&height=300&primaryColor=%23ff0000ff&secondaryColor=%23ffd700ff
https://some.endpoint.com/my_s3_bucket/0123abcd.png?width=300&height=300&letter=t&primaryColor=%23ff0000ff&secondaryColor=%23ffd700ff
Built with the Serverless framework for use with AWS lambda functions and S3 storage.
To deploy to an AWS account, setup the AWS Credential store or environment variables as usual.
- An IDE or plugin that can utilize
.editorconfig
files - An IDE or plugin that can show
tslint
warnings
- Serverless AWS documentation
- TypeScript
- List of the default tslint rules
- ImageMagick is complicated. Read the full ImageMagick documentation for complete details.
-
Install NodeJs 8.10+
-
Install ImageMagick (download or use
choco install imagemagick.tool
) and make sure it is in yourPATH
.Tip: On Windows, some of the tools are named the same as Windows commands (like
convert
) so make sure it is very early in your PATH. -
Fork and clone this repository
-
Copy
serverless-local-example.yml
toserver-local.yml
and configure it according to your environment -
Setup your provider credentials as appropriate for the provider
-
Install the necessary development tools:
- npm
npm install -g yarn
npm install -g serverless
-
Run
yarn
to install and upgrade necessary development libraries- See the AWS Lambda Execution Environment and Available Libraries on which version the
aws-sdk
library should be set to, since it is fixed on their side; thepackage.json
aws-sdk
version should be updated to match the current "AWS SDK for JavaScript" version listed there. - If the serverless library is updated to a new major version in
packages.json
, make sure to check and update theserverless.yml
frameworkVersion
accordingly
- See the AWS Lambda Execution Environment and Available Libraries on which version the
-
Run
npm test
to run unit testsNote: Configure the slow (via
packages.json
call to mocha) and timeout (via calls todescribe...it(...).timeout(ms)
on each test) settings as necessary when testing image processing functions that call out to the external process, which can take longer than average. -
Run a serverless command as necessary; see the Serverless Quick Start documentation
Example deployment to AWS Lambda development (staging):
serverless deploy -v --stage dev
Example deployment of a single function (based on the base function name given in serverless.yml
)
serverless deploy -f image
Example deployment to production:
serverless deploy -v --stage production
Example cleanup:
serverless remove
Some tips:
- AWS Lambda (if in use), already includes the AWS SDK and
ImageMagick
libraries so it only needs referenced as a developer dependency - Any references to running the
serverless
tool can also be run with the symlink/cmdsls
- Run
serverless print
to check your serverless configuration (including variable substitutions) - Run
serverless invoke local -f image --path test/test.json
(or any of the othertestX.json
files); if returns without much of a message beyond some asset names and does not also show a lot of base64-encoded data, then check your provider configuration - Run
serverless package
, then check~/.serverless/cloudformation-template...json
to check your provider configuration and what is going to end up as your AWS CloudFormation stack - Whatever IAM Role (or IAM inline permissions) you supply, should have access to CloudWatch logs and appropriate S3 buckets/paths. Example:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "s3:ListBucket",
"Resource": "arn:aws:s3:::your.bucket.name.here"
},
{
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:GetObject",
"s3:DeleteObject"
],
"Resource": [
"arn:aws:s3:::your.bucket.name.here/directory-one",
"arn:aws:s3:::your.bucket.name.here/directory-one/*",
"arn:aws:s3:::your.bucket.name.here/directory-two",
"arn:aws:s3:::your.bucket.name.here/directory-two/*",
"arn:aws:s3:::your.bucket.name.here"
]
},
{
"Effect": "Allow",
"Action": [
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:DescribeLogGroups",
"logs:DescribeLogStreams",
"logs:PutLogEvents",
"logs:PutRetentionPolicy"
],
"Resource": [
"*"
]
}
]
}
- Unit/non-integration tests (
*.ts
files in thetest
directory) are setup to not be run with the full serverless framework and provider system. Instead, they are meant to test your service layer. (You abstracted the service layer from the provider/serverless handler layer, correct?) For full serverless level but still local (non-live) tests, write JSON files with the necessary data and callsls invoke local --path test/some.test.data.file.name.here.json
. (See thetest/*.json
files for examples.)