Quick Start

If you are starting from scratch, follow the Paperclip's Quick Start to get started. The quick start example will be used as the basis for this usage example. But if you've already got a project you'd like to adapt, the changes should be simple enough to follow along and make similar additions to your own model(s).

The first thing you will need is to setup an image source with Imgix. For this example, lets assume your source domain name is paperclip. Source names are globally unique, so you'll have a different name. Just substitute the name you've chosen for your source.

Starting with this model:

class User < ActiveRecord::Base
  has_attached_file :avatar, :styles => { :medium => "300x300>", :thumb => "100x100>" }
end

Configure Paperclip to use the S3 storage type:

class User < ActiveRecord::Base
  has_attached_file :avatar, {
    :styles => { :medium => "300x300>", :thumb => "100x100>" },
    :storage => :s3,
    :bucket => "paperclip-imgix",
    :s3_credentials => "config/amazon_s3.yml"
  }
end

And then add your S3 credentials to RAILS_ROOT/config/amazon_s3.yml.

Now, to configure this User#avatar field to use Imgix:

class User < ActiveRecord::Base
  has_attached_file :avatar, {
    :styles => { :medium => "300x300>", :thumb => "100x100>" },
    # other configurations
    :imgix => {
        :type => 's3',
        :domain_name => 'paperclip'
    }
  }
end

An S3 Imgix source is not required when storing images in S3. If you are using a different source type or want more information, see how to configure a Web Folder, Web Proxy, or S3.

Likely you'll want to create separate configurations for development, test, and production. You can do that by adding the keys for each environment:

class User < ActiveRecord::Base
  has_attached_file :avatar, {
    :styles => { :medium => "300x300>", :thumb => "100x100>" },
    # other configurations
    :imgix => {
        :development => {
          :type => 's3',
          :domain_name => 'paperclip'
        },
        :test => { … },
        :production => { … }
    }
  }
end

To share configurations with multiple models and to keep all configurations organized, you can put the imgix configuration in a YAML file:

class User < ActiveRecord::Base
  has_attached_file :avatar, {
    :styles => { :medium => "300x300>", :thumb => "100x100>" },
    # other configurations
    :imgix => 'config/imgix.yml'
  }
end

and in RAILS_ROOT/config/imgix.yml:

development:
  type: s3
  domain_name: paperclip
test:
  # …
production:
  # …

And, that's it! Your views don't need to change at all, but they do have some new super powers.