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

The following examples walk through using Cloudinary with CarrierWave in a Rails project. We use a Post model with a picture attribute (a String column) to attach an image to each post.

To get started, define a CarrierWave uploader class and include the Cloudinary plugin. For details, see the CarrierWave documentation.

Define the uploader with tags and versions

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

Set a custom public ID and mount the uploader

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:

Add the form, cache field, and controller save

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:

Eagerly generate versions and display images

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:

Return media metadata and colors

You can ask Cloudinary to include media metadata (IPTC/XMP/EXIF) and predominant colors in the upload response.

Server-side (CarrierWave uploader)

Accessing the metadata in your model

Client-side uploads (Rails helper)

Retrieve metadata for existing assets (Admin API)

Apply a transformation to all versions

If you define multiple versions in your CarrierWave uploader and want to apply the same transformation across all of them, use the process_all_versions helper provided by the Cloudinary CarrierWave plugin.

The cloudinary_transformation processor accepts any options supported by Cloudinary image transformations (for example, effect, quality, crop, width, and height). See the Transformation reference for details.

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).

Legacy CarrierWave: Using the Original Filename as the public_id

Older CarrierWave-based integrations may require explicitly defining the public_id in the uploader to preserve the original filename when uploading assets to Cloudinary.

Server-side (CarrierWave uploader)

This approach predates the use_filename and unique_filename upload options and is maintained here for backward compatibility with existing applications.

Client-side uploads (form helper)

For modern Rails apps, rely on the standard upload options instead of overriding public_id manually.

Check out our Introduction to Cloudinary for Ruby Developers course in the Cloudinary Academy. This self-paced resource provides video-based lessons, sample scripts and other learning material to get you going with Ruby and Cloudinary today.