This add-on is operated by Copenhacken

Fast and secure image processing CDN. Easy integration with your stack.

Last updated April 20, 2024

Image Proxy is a fast and secure image processing CDN (Content Delivery Network) - you can host a single source file of your images and generate different size and format variants through URL parameters.

Image Proxy will load the source image, apply the requested processing, optimize the image file and cache the end result to be served as fast as possible to your users, using the most optimal image format and HTTP version for the requesting browser.

Provisioning the Add-on

Image Proxy can be attached to a Heroku application via the CLI:

$ heroku addons:create imgproxy --app example-app
-----> Adding imgproxy to example-app... done

You can also do this from the Resources section of your application’s configuration page on Heroku.

Application Configuration

Once add-on has been provisioned, the following environment variables will be available in the app configuration:

• IMGPROXY_URL
• IMGPROXY_KEY
• IMGPROXY_SALT
• IMGPROXY_BASE64_ENCODE_URLS

Most client libraries and frameworks will pick up these environment variables and configure things automatically. For custom setups, you should configure your application to use them as provided. Keep in mind these variables might be eventually rotated.

The configuration can be confirmed using the heroku config command:

$ heroku config --app example-app | grep IMGPROXY

Using with Ruby

Edit your Gemfile, adding the following line and run bundle install

gem "imgproxy"

Then generate an Image Proxy URL, for example:

Imgproxy.url_for(
  "http://images.example.com/images/image.jpg",
  crop: {
    width: 500,
    height: 600,
    gravity: {
      type: :nowe,
      x_offset: 10,
      y_offset: 5
    }
  }
)

Using with Ruby on Rails

Edit your Gemfile, adding the following line and run bundle install

gem "imgproxy"

imgproxy.rb comes with the Active Storage support built-in. It is enabled automagically if you load imgproxy gem after rails (basically, just put gem "imgproxy" after gem "rails" in your Gemfile). Otherwise, modify your initializer at config/initializers/imgproxy.rb:

# config/initializers/imgproxy.rb

Imgproxy.extend_active_storage!

Now, to add imgproxy processing to your image attachments, just use the imgproxy_url method:

user.avatar.imgproxy_url(width: 500, height: 400, resizing_type: :fill)

This method will return a URL to your user’s avatar, resized to fill 500x400px on the fly.

Using with Node.js

Add the imgproxy-node dependency to your project:

$ npm install @imgproxy/imgproxy-node

Then generate an Image Proxy URL, for example:

import { generateImageUrl } from '@imgproxy/imgproxy-node';

const url = generateImageUrl({
  url: "https://example.com/image.jpg",
  options: {
    resize: {
      width: 100,
      height: 100,
      type: "fill",
      enlarge: 1,
      extend: { extend: 1 }
    },
    rotate: 90,
    quality: 80,
    format: "webp",
  }
});

Using with Python

Install the imgproxy Python library:

$ pip install imgproxy

Then generate an Image Proxy URL, for example:

import os
from imgproxy import ImgProxy

img_url = ImgProxy(
  "https://example.com/path/to/image.jpg",
  proxy_host=os.environ["IMGPROXY_ENDPOINT"],
  key=os.environ["IMGPROXY_KEY"],
  salt=os.environ["IMGPROXY_SALT"],
  width=800,
  height=400
)

Supported image formats

Conversion between images in PNG, JPEG, WebP, AVIF, GIF, ICO, SVG, HEIC, BMP and TIFF formats is supported.

Removing the add-on

The Image Proxy add-on can be removed via the CLI.

$ heroku addons:destroy bucketeer:test
-----> Removing bucketeer:test from sharp-mountain-4005... done, v20 (free)

Support

All Image Proxy support and runtime issues should be submitted via the Heroku Support channels. We will do our best to assist you.