Public | Automated Build

Last pushed: 2 years ago
Short Description
Docker build for the Giraffe image processor
Full Description


Image pipelines are hard; let's go ride bikes!

This is partly a reaction to looking at the imgix service, which is "not just imagemagick on ec2", and saying that "imagemagick on ec2" sounds an awful lot like something I actually want.

Why call it Giraffe?

I wanted a name with a soft G sound and I didn't have any better ideas. I'm actively soliciting suggestions for a better name.


giraffe is an image processing proxy with the immediate
goal of being placed between an S3 bucket and a cloudfront distribution.

giraffe allows you to store your high-quality original images on S3 and
do any resizing, cropping, filters, etc on demand by simply adding query
parameters to the URL for the original image.

Overview of architecture:

You store original images in an s3 bucket. Something like:


You set up giraffe in ec2 behind an elb, point dns (e.g.: at it, and configure it to point to your bucket.

Finally set up a new cloudfront distribution (e.g.: to sit
in front of and be sure to set it to forward query strings
to origin.


Assuming your image 1.jpg above is a 1080p image and you'd really like to just display a 100x100 thumbnail next to user_1's comments you can do so easily by simply including the following in your markup:

<img src=""
     alt="profile pic" title="user_1" />

The request will hit cloudfront (at, which will turn around and hit your origin at giraffe will check for an image /profile_pictures/1.jpg, if that exists it'll then check for the requested size image at /cache/profile_pictures/1_100_100.jpg in s3:// If it finds it
it will simply return it, otherwise it'll use the original to generate the
cache prefixed resized version.

Supported URL Parameters


  • w, h
  • fit: controls how the output image is fitted to its target dimensions. Valid values for fit include:
    • crop (resize to fill width and height and crop any excess)
    • liquid (resize with liquid rescaling / content-aware resizing / seam carving)
  • crop: controls how the input is aligned when fit=crop. Valid values for crop include:
    • <unset>: crop to the center
    • top (TBD)
    • bottom (TBD)
    • left (TBD)
    • right (TBD)
  • flip (flip horizontally flip=h, vertically flip=v or both flip=hv)
  • rot (rotate, 1-359 degrees)



At a system level you'll need:

  • Python (2.7, 3.3+, or pypy)
  • ImageMagick (remember to use --with-liblqr if you want to be able to use content-aware resizing)

For deployment with Gunicorn you may also want libev.


You need to set the following environment variables for giraffe to work properly:



mkvirtualenv giraffe
pip install -r requirements.txt


nosetests --logging-clear-handlers

Or to test on multiple versions of Python:



Check out


You can now use docker to build and deploy. Simply do:

docker run -d -p 9876:9876 -e AWS_ACCESS_KEY_ID=<your access key> -e AWS_SECRET_ACCESS_KEY=<your secret access key> steder/giraffe


  • documentation of camo functionality (proxying insecure image URLs like atmos/camo
  • documentation of placeholder functionality
  • support more imgix functionality
  • better caching: memcache caching of images is problematic; memcache complains about caching values over 1MB and it is sadly quite easy to do.


Docker Pull Command
Source Repository