{"id":16032616,"url":"https://github.com/steder/giraffe","last_synced_at":"2025-03-18T03:32:37.786Z","repository":{"id":12657866,"uuid":"15329639","full_name":"steder/giraffe","owner":"steder","description":"Python-based Image Proxy inspired by imgix and github's atmos/camo","archived":false,"fork":false,"pushed_at":"2022-12-08T09:31:00.000Z","size":1604,"stargazers_count":12,"open_issues_count":7,"forks_count":2,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-10-15T21:38:45.286Z","etag":null,"topics":["atmos","bucket","camo","crop","giraffe","image-proxy","imgix","s3-bucket"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/steder.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-12-20T04:09:55.000Z","updated_at":"2022-11-08T07:58:12.000Z","dependencies_parsed_at":"2023-01-11T20:19:10.527Z","dependency_job_id":null,"html_url":"https://github.com/steder/giraffe","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steder%2Fgiraffe","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steder%2Fgiraffe/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steder%2Fgiraffe/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steder%2Fgiraffe/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/steder","download_url":"https://codeload.github.com/steder/giraffe/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221706267,"owners_count":16867174,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["atmos","bucket","camo","crop","giraffe","image-proxy","imgix","s3-bucket"],"created_at":"2024-10-08T21:23:17.104Z","updated_at":"2024-10-27T16:44:21.697Z","avatar_url":"https://github.com/steder.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Giraffe\n\nImage pipelines are hard; let's go ride bikes!\n\nThis 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.\n\nMore 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.\n\nInstead, we moved to uploading original images to S3 and letting the resizing, overlays, etc happen dynamically in Giraffe.\n\n![travis ci build status](https://travis-ci.org/steder/giraffe.png)\n\n## Why call it Giraffe?\n\nI wanted a name with a soft G sound and I didn't have any better ideas.  \n\n## About\n\n`giraffe` is an image processing proxy with the immediate\ngoal of being placed between an S3 bucket and a cloudfront distribution.\n\n`giraffe` allows you to store your high-quality original images on S3 and\ndo any resizing, cropping, filters, etc on demand by simply adding query\nparameters to the URL for the original image.\n\n### Overview of architecture:\n\nYou store original images in an s3 bucket.  Something like:\n\n```\ns3://media.example.com/profile_pictures/1.jpg\n```\n\nYou 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.\n\nFinally set up a new `cloudfront` distribution (e.g.: `hash.cloudfront.net`) to sit\nin front of `images.example.com` and be sure to set it to forward query strings\nto origin.\n\n### Example\n\nAssuming 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:\n\n```\n\u003cimg src=\"http://hash.cloudfront.net/media.example.com/profile_pictures/1.jpg?w=100\u0026h=100\"\n     alt=\"profile pic\" title=\"user_1\" /\u003e\n```\n\nThe 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\nit will simply return it, otherwise it'll use the original to generate the\n`cache` prefixed resized version.\n\n## Supported URLs / Resources\n\n - Test UI: `/`\n - Generate and retrieve a placeholder image: `/placeholders/\u003cplaceholder name\u003e`\n - Proxy a remote image ala atmos: `/proxy/\u003cHMAC\u003e?url=\u003cURL\u003e`\n - Retrieve an image with resizing: `/\u003cbucket\u003e/\u003cpath\u003e`\n \n### Placeholder Images\n \nGenerates an image with simple placeholder text.  Typically a simple box with the image size (e.g.: `WxH`) as text inside it.\n\nSupported params:\n\n - bg: set the background color with an RGB value (defaults to 'fff' for white backgrounds)\n\n### Resizing\n\n`/\u003cbucket\u003e/path?w=1024\u0026h=768`\n\nSupported params:\n\n - w, h: width and height\n - fit: controls how the output image is fitted to its target dimensions.  Valid values for `fit` include:\n  - crop (resize to fill width and height and crop any excess)\n  - liquid (resize with liquid rescaling / content-aware resizing / seam carving)\n - crop: controls how the input is aligned when `fit=crop`.  Valid values for `crop` include:\n   * \u003cunset\u003e: crop to the center\n   * top (TBD)\n   * bottom (TBD)\n   * left (TBD)\n   * right (TBD)\n - flip (flip horizontally `flip=h`, vertically `flip=v` or both `flip=hv`)\n - rot (rotate, 1-359 degrees)\n - q: decimal percent quality setting, defaults to 75 (aka 75%)\n - overlay: path to a file in the current s3 bucket to use as an overlay\n - ox: offset to the X position of the overlay\n - oy: offset to the Y position of the overlay\n - ow: width to scale the overlay to before compositing it with your base image\n - oh: ditto above but for height\n - bg: background color to use when overlaying images (useful for grayscale images with transparency)\n\n## Setup\n\n### Dependencies\n\nAt a system level you'll need:\n - `Python` (3.7+, or pypy3)\n - `ImageMagick` (remember to use `--with-liblqr` if you want to be able to use content-aware resizing)\n\nFor deployment with Gunicorn you may also want `libev`.\n\n### Configuration\n\nYou need to set the following environment variables for giraffe to work properly:\n\n - AWS_ACCESS_KEY_ID\n - AWS_SECRET_ACCESS_KEY\n\n### Development\n\n```\nmkvirtualenv giraffe\npip install -r requirements.txt\n```\n\n#### Testing\n\n```\npytest\n```\n\n### Deployment\n\nCheck out `install.sh`\n\n## Docker\n\nYou can now use docker to build and deploy.  Simply do:\n\n    docker run -d -p 9876:9876 -e AWS_ACCESS_KEY_ID=\u003cyour access key\u003e -e AWS_SECRET_ACCESS_KEY=\u003cyour secret access key\u003e steder/giraffe\n\n## TODO\n\n - documentation of camo functionality (proxying insecure image URLs like [atmos/camo](https://github.com/atmos/camo)\n - documentation of placeholder functionality\n - support more imgix functionality\n - better caching: memcache caching of images is problematic; memcache complains about caching values over 1MB and it is sadly quite easy to do.\n\n## Sites\n\n - Threadless.com\n - Typetees.com\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsteder%2Fgiraffe","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsteder%2Fgiraffe","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsteder%2Fgiraffe/lists"}