Ruby/Rails SDK
This page provides an in-depth introduction to the Ruby/Rails SDK.
Overview
Cloudinary's Ruby/Rails SDK provides simple, yet comprehensive image and video upload, transformation, optimization, and delivery capabilities that you can implement using code that integrates seamlessly with your existing Ruby/Rails application.
You may also find our Glossary helpful to understand Cloudinary-specific terminology.
For details on all new features and fixes from previous versions, see the CHANGELOG.
Quick example: Transformations
Take a look at the following transformation code and the image it delivers:
cl_image_tag("front_face.png", :secure=>true, :transformation=>[ {:width=>150, :height=>150, :gravity=>"face", :crop=>"thumb"}, {:radius=>20}, {:effect=>"sepia"}, {:overlay=>"cloudinary_icon_blue", :gravity=>"south_east", :x=>5, :y=>5, :width=>50, :opacity=>60, :effect=>"brightness:200"}, {:angle=>10} ])

This relatively simple code performs all of the following on the original front_face.jpg image before delivering it:
- Crop to a 150x150 thumbnail using face-detection gravity to automatically determine the location for the crop
- Round the corners with a 20 pixel radius
- Apply a sepia effect
- Overlay the Cloudinary logo on the southeast corner of the image (with a slight offset). The logo is scaled down to a 50 pixel width, with increased brightness and partial transparency (opacity = 60%)
- Rotate the resulting image (including the overlay) by 10 degrees
- Convert and deliver the image in PNG format (the originally uploaded image was a JPG)
And here's the URL that would be included in the image tag that's automatically generated from the above code:
In a similar way, you can transform a video.
- See all possible transformations in the Transformation URL API reference.
- See more examples of image and video transformations using the
cloudinary_gem
library.
Quick example: File upload
The following Ruby code uploads the dog.mp4
video to the specified account sub-folder using the public_id, my_dog
. The video will overwrite the existing my_dog
video if it exists. When the video upload is complete, the specified notification URL will receive details about the uploaded media asset.
Cloudinary::Uploader.upload("dog.mp4", :folder => "myfolder/mysubfolder/", :public_id => "my_dog", :overwrite => true, :notification_url => "https://mysite.example.com/notify_endpoint", :resource_type => "video")
Ruby gem features
Cloudinary provides a Ruby gem (open source) that simplifies the integration with your Ruby and Ruby on Rails applications:
- Build URLs for image and video transformations
- Rails view helper tags for embedding and transforming images
- API wrappers: file upload, administration, sprite generation and more
- Server-side file upload + direct unsigned file upload from the browser using the jQuery plugin
- Migration tool
- Active Storage integration
- CarrierWave plugin
- Static image syncing for CDN delivery
- General Ruby integration for non-Rails frameworks such as Sinatra
Installation
Cloudinary's Ruby library is available as an open-source Ruby gem.
To install the Cloudinary Ruby gem, run:
If you use Rails 3.x or later, edit your Gemfile, add the following line and run bundle.
Or in Rails 2.x, edit your environment.rb and add:
Configuration
To use the Cloudinary Ruby/Rails library, you have to configure at least your cloud_name
. Your api_key
and api_secret
are also needed for secure API calls to Cloudinary (e.g., image and video uploads). You can find your account-specific configuration credentials in the Dashboard page of the account console.
In addition to the required configuration parameters, you can define a number of optional configuration parameters if relevant.
You can set your configuration parameters:
- Individually, by passing configuration parameters in Cloudinary method calls
- Globally by defining the CLOUDINARY_URL environment variable (required parameters only)
- Globally in a cloudinary.yml file
- Globally in a Rails initializer file
- You can always override the values specified in
cloudinary.yml
or initializer file by passing different values in specific Cloudinary calls. - If you use more than one method of setting configuration options, the order of precedence is:
CLOUDINARY_URL
->cloud_name
->cloudinary.yml
/cloudinary.rb
- For backward compatibility reasons, the default value of the optional
secure
configuration parameter isfalse
. However, for most modern applications, it's recommended to configure thesecure
parameter totrue
to ensure that your transformation URLs are always generated as HTTPS.
Setting the CLOUDINARY_URL environment variable
You can configure the required cloud_name
, api_key
, and api_secret
by defining the CLOUDINARY_URL environment variable. The CLOUDINARY_URL value is available in the Dashboard page of the account console. When using Cloudinary through a PaaS add-on (e.g., Heroku or AppFog), this environment variable is automatically defined in your deployment environment. For example:
Set additional parameters, for example upload_prefix and cname, to the environment variable:
CLOUDINARY_URL=cloudinary://my_key:my_secret@my_cloud_name?cname=mydomain.com&upload_prefix=myprefix.com
Configuring in the cloudinary.yml file
You create the cloudinary.yml under the config directory of your Rails project.
You can download a pre-customized cloudinary.yml configuration file in the Dashboard page of your Management Console.
Here's an example of a cloudinary.yml
file:
production: cloud_name: "sample" api_key: "874837483274837" api_secret: "a676b67565c6767a6767d6767f676fe1" secure: true
Configuring in the Rails initializer file
You can place a file named cloudinary.rb in the /config/initializers folder of your Rails project. Here's some sample initializer code:
Cloudinary.config do |config| config.cloud_name = 'sample' config.api_key = '874837483274837' config.api_secret = 'a676b67565c6767a6767d6767f676fe1' config.secure = true end
Ruby capitalization and data type guidelines
When using the Ruby/Rails SDK, keep these guidelines in mind:
- Parameter names:
snake_case
. For example: public_id - Classes:
PascalCase
. For example: PictureUploader - Methods:
snake_case
. For example: cl_image_upload_tag - Pass parameter data as:
Hash
Sample projects
For additional useful code samples and to learn how to integrate Cloudinary with your Rails applications, take a look at our Sample Projects.
- Basic Ruby sample: Uploading local and remote images to Cloudinary and generating various transformation URLs.
- Basic Rails sample: Uploading local and remote images in a Rails project while embedding various transformed images in a Rails web view.
- Rails Photo Album: A fully working web application. It uses CarrierWave to manage images of an album model (database). Performs image uploading both from the server side and directly from the browser using a jQuery plugin.
- Get your first Ruby/Rails SDK project up and running in ~5 minutes with the Ruby/Rails SDK quick start.
- Learn more about uploading images and videos.
- See examples of powerful image and video transformations using Ruby code
and see our image transformations and video transformation docs. - Check out Cloudinary's asset administration capabilities, for example, renaming and deleting assets, adding tags and metadata to assets, and searching for assets.
- Make sure to read about Rails Carrierwave, Attachinary, and ActiveStorage integrations.
- Stay tuned for updates, tips and tutorials in Product Updates and Blog Posts.