CarrierWave integration

If you support dynamically uploading images in your Ruby on Rails application, the images are probably attached to a certain model entity. Rails uses ActiveRecord for model entities by default, while Mongoid documents are used for a MongoDB-based model. Examples might include keeping the image as the 'picture' attribute of a Post entity or as the 'profile_picture' attribute of a User entity.

The CarrierWave gem can be useful for integrating image uploads with your model. By default, CarrierWave stores images on the local hard drive, but it also has additional plugins available for image storing and transformation.

The Cloudinary gem provides a plugin for CarrierWave. Using this plugin enables you to enjoy the benefits of CarrierWave for easily uploading images from HTML forms to your model, while enjoying the great benefits of Cloudinary: uploaded images are stored in cloud, transformed in the cloud, and delivered automatically through a CDN.

CarrierWave installation and setup

To use the optional integration module for uploading images with ActiveRecord or Mongoid using CarrierWave, install the CarrierWave gem:

Rails 3.x Gemfile:

Rails 5.x environment.rb

Upload examples

Below is a short example that demonstrates using Cloudinary with CarrierWave in your Rails project. In this example, we use the Post model entity to support attaching an image to each post. Attached images are managed by the 'picture' attribute (column) of the Post entity.

To get started, first define a CarrierWave uploader class and tell it to use the Cloudinary plugin. For details, see the CarrierWave documentation.

In this example, we'll convert the uploaded image to a PNG before storing it in the cloud. We'll also assign it the post_picture tag. We define two additional transformations required for displaying the image in our site: 'standard' and 'thumbnail'. A randomly generated unique Public ID is generated for each uploaded image and persistently stored in the model.

In the following example, we explicitly define a public_id based on the content of the 'short_name' attribute of the 'Post' entity.

The 'picture' attribute of Post is simply a String (a DB migration script is needed of course). We mount it to the 'PictureUploader' class we've just defined:

In our HTML form for Post editing, we add a File field for uploading the picture and also a hidden 'cache' field for supporting page reloading and validation errors without losing the uploaded picture. The example below is in 'HAML' (you can of course do exactly the same using 'ERB'):

In our controller, we save or update the attributes of the post in the standard way. For example:

At this point, the image uploaded by the user to your server is uploaded to Cloudinary, which also assigned the specified Public ID and tag and converts it to PNG. The Public ID together with the version of the uploaded image are stored in the 'picture' attribute of our Post entity. Note that by default the transformations are not generated at this point; they are generated only when an end-user accesses them for the first time. This is true unless you specify 'process :eager => true' or simply 'eager' for each transformation.

Now you can use standard image_tag calls for displaying the uploaded images and their derived transformations and the Cloudinary gem automatically generates the correct full URL for accessing your resources:

Custom and dynamic transformations

Cloudinary's plugin for CarrierWave supports all standard CarrierWave resize and crop options. In addition, you can apply any custom transformation supported by Cloudinary using the cloudinary_transformation method. Calling cloudinary_transformation can be also done in combination with the standard CarrierWave resize and crop methods. The following uploader class shows a common example of using custom transformations:

You can take this further and apply chained transformations to achieve more complex results. These transformations can be applied as an incoming transformation while uploading or as part of the different versions that are generated either lazily or eagerly while uploading. The following uploader class includes such chained transformations applied using the transformation parameter of the cloudinary_transformation method.

Some websites have a graphic design that forces them to display the same images in many different dimensions. Formally defining multiple uploader versions can be a hassle. You can still use CarrierWave and leverage Cloudinary's dynamic transformations by applying desired transformations while building your view. Any version can be generated dynamically from your view with no dependency on CarrierWave versions. To accomplish this, use the full_public_id attribute with cl_image_tag to build cloud-based transformation URLs for the uploaded images attached to your model.

Custom coordinate-based cropping

If you allow your users to manually select the cropping area, we recommend to keep the x,y coordinates persistently in the model to enable different cropping on the original image in the future. The following uploader class fetches the custom coordinates from attributes of the model object. The custom_crop method in this example returns a Hash of additional Cloudinary transformation parameters to apply.

If you want to store only the cropped version of the image, you can use an incoming transformation. This way, the original image is not stored in the cloud; only the cropped version. You can then use further transformations to resize the cropped image. The following example calls process :custom_crop in the class itself (instead of in a 'version') while the custom-coordinates are kept as transient attributes on the model (defined with attr instead of storing them persistently).