Active Storage integration

Active Storage can be useful for integrating image uploads with your model. The Cloudinary gem enables you to enjoy the benefits of Active Storage for easily uploading images from HTML forms to your model, while enjoying the great benefits of Cloudinary: uploaded images are stored in the cloud, transformed and manipulated in the cloud, and delivered automatically through a CDN.

The following documentation assumes you have already set up Active Storage within your Rails 5+ application, and teaches you how to configure Active Storage to work with Cloudinary for image uploads and image delivery.

Active Storage configuration

Declare the Cloudinary service in the config/storage.yml file by adding a new entry with a custom name (e.g., cloudinary) and the service configuration:

Copy to clipboard
cloudinary:      
  service: Cloudinary
  # Any other settings you want, to be sent on all requests, can be included here as well.

Tell Active Storage which service to use by setting Rails.application.config.active_storage.service. As each environment will likely use a different service, it is recommended to do this on a per-environment basis. For example, to use the cloudinary service in the development environment, you would add the following to config/environments/development.rb:

Copy to clipboard
# Use Cloudinary.
config.active_storage.service = :cloudinary

Direct uploads

Active Storage already supports uploading directly from the client to the cloud. After adding Cloudinary as a service, use direct uploading as usual:

  1. Include activestorage.js in your application's JavaScript bundle.

    Using the asset pipeline:

    Copy to clipboard
    //= require activestorage

    Using the npm package:

    Copy to clipboard
    require("@rails/activestorage").start()
  2. Annotate file inputs with the direct upload URL.

    Copy to clipboard
    <%= form.file_field :avatar, direct_upload: true %>

Note
You cannot specify an upload preset or other upload parameters on a per-upload basis while using Active Storage. There are however two ways to globally specify upload parameters for all uploads:

  • As an upload preset (or upload parameters) in the Rails service configuration (as top-level parameters)
  • As a default upload preset specified via the console which will be applied to all uploads without any extra code on the Rails side

Image delivery

Use the url_for helper method to generate a permanent URL link, that upon access, redirects to a Cloudinary endpoint. This helper has been enhanced to also accept any Cloudinary image transformations for lazily transforming the image on delivery (as per all Cloudinary dynamic URLs). For example, to deliver a user's avatar image scaled down to 300x200 with the 'cartoonify' effect applied:

Copy to clipboard
<%= url_for(@user.avatar, width: 300, height: 200, effect: "cartoonify") %>

Important
The enhanced url_for method makes the variant method irrelevant as the variant method would try to create a new resource and upload it to Cloudinary, instead of letting Cloudinary handle the transformation. As such, the variant method is not needed or supported.