https://github.com/steder/giraffe
Python-based Image Proxy inspired by imgix and github's atmos/camo
https://github.com/steder/giraffe
atmos bucket camo crop giraffe image-proxy imgix s3-bucket
Last synced: 3 months ago
JSON representation
Python-based Image Proxy inspired by imgix and github's atmos/camo
- Host: GitHub
- URL: https://github.com/steder/giraffe
- Owner: steder
- License: mit
- Created: 2013-12-20T04:09:55.000Z (over 11 years ago)
- Default Branch: master
- Last Pushed: 2022-12-08T09:31:00.000Z (over 2 years ago)
- Last Synced: 2024-10-15T21:38:45.286Z (8 months ago)
- Topics: atmos, bucket, camo, crop, giraffe, image-proxy, imgix, s3-bucket
- Language: Python
- Homepage:
- Size: 1.53 MB
- Stars: 12
- Watchers: 6
- Forks: 2
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# Giraffe
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.
More specifically, this started out as something to help out the design team and ended up replacing a venerable set of cronjobs that copied images from all over, resized them, and uploaded dozens of variants to S3.
Instead, we moved to uploading original images to S3 and letting the resizing, overlays, etc happen dynamically in Giraffe.
## Why call it Giraffe?
I wanted a name with a soft G sound and I didn't have any better ideas.
## About
`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:
```
s3://media.example.com/profile_pictures/1.jpg
```
You set up `giraffe` in `ec2` behind an `elb`, point dns (e.g.: `images.example.com`) at it, and configure it to point to your bucket.
Finally set up a new `cloudfront` distribution (e.g.: `hash.cloudfront.net`) to sit
in front of `images.example.com` and be sure to set it to forward query strings
to origin.
### Example
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:
```
```
The request will hit `cloudfront` (at `hash.cloudfront.com`), which will turn around and hit your origin at `images.example.com`. `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://media.example.com`. If it finds it
it will simply return it, otherwise it'll use the original to generate the
`cache` prefixed resized version.
## Supported URLs / Resources
- Test UI: `/`
- Generate and retrieve a placeholder image: `/placeholders/`
- Proxy a remote image ala atmos: `/proxy/?url=`
- Retrieve an image with resizing: `//`
### Placeholder Images
Generates an image with simple placeholder text. Typically a simple box with the image size (e.g.: `WxH`) as text inside it.
Supported params:
- bg: set the background color with an RGB value (defaults to 'fff' for white backgrounds)
### Resizing
`//path?w=1024&h=768`
Supported params:
- w, h: width and height
- 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:
* : 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)
- q: decimal percent quality setting, defaults to 75 (aka 75%)
- overlay: path to a file in the current s3 bucket to use as an overlay
- ox: offset to the X position of the overlay
- oy: offset to the Y position of the overlay
- ow: width to scale the overlay to before compositing it with your base image
- oh: ditto above but for height
- bg: background color to use when overlaying images (useful for grayscale images with transparency)
## Setup
### Dependencies
At a system level you'll need:
- `Python` (3.7+, or pypy3)
- `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`.
### Configuration
You need to set the following environment variables for giraffe to work properly:
- AWS_ACCESS_KEY_ID
- AWS_SECRET_ACCESS_KEY
### Development
```
mkvirtualenv giraffe
pip install -r requirements.txt
```
#### Testing
```
pytest
```
### Deployment
Check out `install.sh`
## Docker
You can now use docker to build and deploy. Simply do:
docker run -d -p 9876:9876 -e AWS_ACCESS_KEY_ID= -e AWS_SECRET_ACCESS_KEY= steder/giraffe
## TODO
- documentation of camo functionality (proxying insecure image URLs like [atmos/camo](https://github.com/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.
## Sites
- Threadless.com
- Typetees.com