ben-ng / thumbd

Node.js/AWS/ImageMagick-based image thumbnailing service.

Thumbd

Author: Benjamin Coe @benjamincoe

Thumbd is an image thumbnailing server built on top of Node.js, SQS, S3, and ImageMagick.

Setup

apt-get install imagemagick
npm install thumbd

Thumbd requires the following environment variables to be set:

• AWS_KEY the key for your AWS account (the IAM user must have access to the appropriate SQS and S3 resources).
• AWS_SECRET the AWS secret key.
• BUCKET the bucket to download the original images from. The thumbnails will also be placed in this bucket.
• SQS_QUEUE the queue URL to listen for image thumbnaling. You can find this URL from your AWS control panel, it begins with https://.

You can export these variables to your environment, or specify them when running the thumbd CLI.

Personally, I set these environment variables in a .env file and execute thumbd using Foreman.

Server

The thumbd server:

• listens for thumbnailing jobs on the queue specified.
• downloads the original image from our thumbnailng S3 bucket, or from an HTTP(s) resource.
  • HTTP resources are prefixed with http:// or https://.
  • S3 resources are a path to the image in the S3 bucket indicated by the BUCKET environment variable.
• Uses ImageMagick to perform a set of transformations on the image.
• uploads the thumbnails created back to S3, with the following naming convention: [original filename excluding extension]_[thumbnail suffix].jpg

Assume that the following thumbnail job was received over SQS:

{
	"original": "example.png",
	"descriptions": [
		{
			"suffix": "tiny",
			"width": 48,
			"height": 48
		},
		{
			"suffix": "small",
			"width": 100,
			"height": 100,
			"background": "red"
		},
		{
			"suffix": "medium",
			"width": 150,
			"height": 150,
			"strategy": "bounded"
		}
	]
}

Once thumbd processes the job, the files stored in S3 will look something like this:

• /example.png
• /example_tiny.jpg
• /example_small.jpg
• /example_medium.jpg

Thumbnail Descriptions

The descriptions received in the thumbnail job describe the way in which thumbnails should be generated.

description accepts the following keys:

• suffix a suffix describing the thumbnail.
• width the width of the thumbnail.
• height the height of the thumbnail.
• background background color for matte.
• strategy indicate an approach for creating the thumbnail.
  • matted maintain aspect ratio, places image on width x height matte.
  • bounded (default) maintain aspect ratio, don't place image on matte.
  • fill both resizes and zooms into an image, filling the specified dimensions.

CLI

Starting the server:

thumbd server --aws_key=<key> --aws_secret=<secret> --tmp_dir=</tmp> --sqs_queue=<sqs queue name> --bucket=<s3 thumbnail bucket>

Manually submitting an SQS thumbnailing job (useful for testing purposes):

thumbd thumbnail --remote_image=<path to image s3 or http> --thumbnail_descriptions=<path to thumbnail description JSON file> --aws_key=<key> --aws_secret=<secret> --sqs_queue=<sqs queue name>

• remote_image indicates the S3 object to perform the thumbnailing operations on.
• thumbnail_descriptions the path to a JSON file describing the dimensions of the thumbnails that should be created (see example.json in the data directory).

The Future

thumbd is a rough first pass at creating an efficient, easy to deploy, thumbnailing pipeline. I need thumbd for work, and will be actively contributing to this project.

Copyright

Copyright (c) 2012 Attachments.me. See LICENSE.txt for further details.