> ## Documentation Index > Fetch the complete documentation index at: https://cloudinary.com/documentation/llms.txt > Use this file to discover all available pages before exploring further. # Ruby/Rails quick start [readme-version-support-link]:https://github.com/cloudinary/cloudinary_gem#Version-Support This quick start lets you get an end-to-end implementation up and running using the Ruby/Rails SDK in 5 minutes or less. #### Prerequisites **To perform this quick start, you'll need:** * A Cloudinary account. If you don't have one yet, you can quickly [register for free](https://cloudinary.com/users/register_free). * Your product environment credentials. You can find your [credentials](product_environment_settings#api_keys) on the [API Keys](https://console.cloudinary.com/app/settings/api-keys) page of the Cloudinary Console Settings. * To use your **API environment variable**, copy the provided format and replace the `` and `` placeholders with the actual values found on the page. Your cloud name will already be correctly included in the format. * A working Ruby/Rails development environment with a [supported version][readme-version-support-link] of Ruby/Rails. > **NOTES**: > > * This quick start is designed for quick onboarding. It doesn't necessarily employ coding best practices and the code you create here isn't intended for production. > * If you aren't familiar with Cloudinary, you may want to first take a look at the [Developer Kickstart](dev_kickstart) for a hands-on, step-by-step introduction to Cloudinary features. You may also find our [Glossary](cloudinary_glossary) helpful to understand Cloudinary-specific terminology. ## 1. Set up and configure the SDK ### Install the SDK In a terminal, in your Ruby environment, run: ```ruby gem install cloudinary ``` ### Configure Cloudinary In your project, create a new file called `config.rb` with the code below. Make sure to update it to use your product environment's credentials: config.rb ```ruby # Replace the 'config_from_url' string value below with your # product environment's credentials, available from your Cloudinary console. # ===================================================== require 'cloudinary' Cloudinary.config_from_url("cloudinary://API_KEY:API_SECRET@CLOUD_NAME") ``` > **INFO**: When writing your own applications, follow your organization's policy on storing secrets and don't expose your API secret. What's happening here? You've just told the SDK to work with your product environment credentials using your product environment's **API environment variable URL**. This is just one of several ways to [configure credentials](rails_integration#configuration). In addition to configuring your product environment credentials, you've also applied an additional optional configuration that tells the SDK to generate Cloudinary URLs as 'https'. There are several other [optional configuration options](cloudinary_sdks#configuration_parameters). ### Reference the configuration from a ruby script In your project, create a new file called `quickstart.rb`. For the sake of this quick start, you'll put all the Cloudinary code other than the configuration in this single file and only run it at the end. To reference your product environment configuration from this new file, add: quickstart.rb ```ruby require 'cloudinary' if Cloudinary.config.api_key.blank? require './config' end puts 'My cloud name is:' + Cloudinary.config.cloud_name ``` What's happening here? You're requiring the config file you created in the previous step. Just as a debug validation, when this script runs, it will also print the cloud name it imported from the config file. ## 2. Upload files To upload some remote files to Cloudinary, paste the following to the end of your `quickstart.rb` file: quickstart.rb (continued) ```ruby ## Upload two files using the Upload API: # Use the uploaded filename as the asset's public ID + allow overwriting the asset with new versions. upload1=Cloudinary::Uploader.upload("https://cloudinary-devs.github.io/cld-docs-assets/assets/images/model.jpg", use_filename:true, unique_filename:false, overwrite:true ) # Retrieve some attributes from the first upload response. puts "File size of the #{upload1['public_id']}.#{upload1['format']} #{upload1['resource_type']}: #{upload1['bytes']/1024} KB" # Manually set the asset's public ID + allow overwriting asset with new versions. upload2=Cloudinary::Uploader.upload("https://cloudinary-devs.github.io/cld-docs-assets/assets/images/coffee_cup.jpg", public_id: "coffee", unique_filename: false, overwrite: true ) # Retrieve some attributes from the second upload response. puts "File size of the #{upload2['public_id']}.#{upload2['format']} #{upload2['resource_type']}: #{upload2['bytes']/1024} KB" ``` What's happening here? When you run this code, you'll upload two files by specifying the URL of their current location. (Cloudinary also supports uploading from a local path or other [file source options](upload_parameters#required_file_parameter)). These upload calls use some optional upload parameters to control the way the assets are uploaded, for example, how the [public ID](cloudinary_glossary#public_id) is set, as described in the code comments. After each upload call, you'll print some attributes of the uploaded asset, taken from the upload response. ## 3. Get and use details of an image Paste these two snippets to perform some management operations on the assets you previously uploaded: ### Return details of an existing resource quickstart.rb (continued) ```ruby ## Manage existing assets using the Admin API # Retrieve and print the details for a specific stored asset, # including the optional `faces` data, # based on the public ID returned in the previous upload. my_asset = upload1['public_id'] puts %{ Asset details: ================= } jj details = Cloudinary::Api.resource(my_asset, faces: true) puts %{ ================================ } ``` ### Retrieve and update specific attributes of an asset quickstart.rb (continued) ```ruby # Find out how many faces are in the image, and depending on result, tag the image accordingly. facecount = details['faces'].count puts "Number of faces in this image: #{facecount}" if facecount > 0 asset_update=Cloudinary::Api.update(my_asset, tags: "people") else asset_update=Cloudinary::Api.update(my_asset, tags: "products") end asset_tags = asset_update['tags'] puts "Asset tags: #{asset_tags}" ``` What's happening here? The above two code snippets use the `resource` Admin API method to do the following for an asset that's already stored in your product environment: * Return and print the JSON response containing the details of a specific asset * Check the value of a specific attribute (number of faces) returned from the response * Change the value of an attribute (tags) of the asset ## 4. Transform images Add this code to your file in order to generate a few different transformation URLs on the two assets you previously uploaded: quickstart.rb (continued) ```ruby ## Generate transformation URLs for previously uploaded assets. my_asset1 = upload1['public_id']+'.jpg' my_asset2 = upload2['public_id']+'.jpg' # Scale and then crop the excess to 'fill' 640*200px banner-shape, focussed on the largest face (if any). puts Cloudinary::Utils.cloudinary_url(my_asset1, transformation: {crop: "fill", gravity: "face", width: 640, height: 200, } ) # Create a 200px square (1:1 aspect ratio) thumbnail, then round to a circle to get a profile photo of the face. puts Cloudinary::Utils.cloudinary_url(my_asset1, transformation: [ {crop: "thumb", gravity: "face",width: 200, aspect_ratio: "1.0"}, {radius: "max"} ]) # Deliver a URL link to the original of the second image. puts Cloudinary::Utils.cloudinary_url(my_asset2) # Scale & crop to a portrait image (6:10 aspect ratio), apply a sepia effect, # and automatically optimize the image quality and file format to best balance # between visual quality and small file size. puts Cloudinary::Utils.cloudinary_url(my_asset2, transformation: [ {crop: "fill", aspect_ratio: "0.6", width: 400}, {effect: "sepia"}, {fetch_format: "auto"}, {quality: "auto"} ]) ``` What's happening here? Each of the above pieces of code will generate (and prints to the console) a delivery URL with different transformations applied as described in the code comments. The first transformation involves only a single transformation 'action' (resize). The third URL generates a delivery URL of the originally uploaded asset with no transformations. The second and fourth transformations apply several transformation actions, where each action is 'chained' onto the result of the previous action when the transformed image is generated. Note that these commands only generate the transformation URL string. The Cloudinary platform will generate and cache the transformed images on-the-fly the first time the URL is delivered in a browser. > **TIP**: If you're working with Ruby on Rails, you can optionally use the [cl_image_tag](rails_image_manipulation#the_cl_image_tag_method) Rails helper method instead of `cloudinary_url` to auto-generate a complete image tag with the transformation URL as the `src` value. ## 5. Run your code In your Ruby IDE or in a terminal (from the `/scripts` folder of your project), run your `quickstart.rb` script and take a look at the output you get from each step of this quick start: ```ruby ruby quickstart.rb ``` Tell me more about the output When you run your quickstart file, you'll see the following as they occur: * Your cloud name is printed as retrieved from your config file. * You'll get a line telling you the file size of each uploaded asset. * The next section displays the full JSON response of the `resources` method, listing attributes of the **first** asset you uploaded. * Next, you'll get a line telling you how many faces Cloudinary identified in the first image you uploaded and which tag it applied to the asset based on the face count. * Lastly, you'll see the four generated transformation/delivery URLs. You can paste your generated URLs into browser tabs, and Cloudinary will generate the requested transformed images on the fly. ```json My cloud name is: my_cloud File size of the model image: 143 KB File size of the coffee image: 677 KB Asset details: =================` { "asset_id": "52a1578d3346d0e104e044698eada9d5", "public_id": "model", "format": "jpg", "version": 1651574950, ... ... } ================================ Number of faces in this image: 1 Asset tags: ["people"] https://res.cloudinary.com/my_cloud/image/upload/c_fill,g_face,h_200,w_640/model.jpg https://res.cloudinary.com/my_cloud/image/upload/ar_1.0,c_thumb,g_face,w_200/r_max/model.jpg https://res.cloudinary.com/my_cloud/image/upload/coffee.jpg https://res.cloudinary.com/my_cloud/image/upload/ar_0.6,c_fill,w_400/e_sepia/f_auto/q_auto/coffee.jpg ``` Want to make it more interesting? Once you've got this short script running, here are some ideas to play a bit more: * In [step 2](#2_upload_files), try uploading your own images instead of the two URLs provided. You can reference files with a relative path instead of referencing URLs. * In [step 3](#3_get_and_use_details_of_an_image), change the definition of `my_asset` to be `my_asset = upload2['public_id']` and re-run your script. In this case, you'll get back the details of the 'coffee' image, which doesn't have any faces, and thus should be tagged as 'products'. * In [step 4](#4_transform_images), modify the transformation values or even try to add some new transformations. You can find all available transformations in the [Transformation URL API reference](transformation_reference). > **NOTE**: > > This quick start uses some options that are specific to image files (such as the **facecount** response key used in [step 3](#3_get_and_use_details_of_an_image) and the **sepia** transformation effect used in [step 4](#4_transform_images)), so if you want to play around with uploading and performing steps on videos instead of images, you'll need to adjust those elements of this script. ## View the completed code You can find the full code example for this quick start on [GitHub](https://github.com/cloudinary-devs/ruby-sdk-quickstart). ## Next steps * Learn more about the Ruby/Rails SDK by visiting the other pages in this SDK guide. * Get comprehensive details about Cloudinary features and capabilities: * [Upload guide](upload_images): Provides details and examples of the upload options. * [Image transformations guide](image_transformations): Provides details and examples of the transformations you can apply to image assets. * [Video transformations guide](video_manipulation_and_delivery): Provides details and examples of the transformations you can apply to video assets. * [Transformation URL API Reference](transformation_reference): Provides details and examples of all available transformation parameters. * [Admin API guide](admin_api): Provides details and examples of the methods available for managing and organizing your media assets.  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.