Some time ago I wrote an article Uploading Files With Rails and Shrine that explained how to introduce a file uploading feature into your Rails application with the help of the Shrine gem. There are, however, a bunch of similar solutions available, and one of my favorites is Dragonfly—an easy-to-use uploading solution for Rails and Rack created by Mark Evans. 

We covered this library early last year but, as with most software, it helps to take a look at libraries from time to time to see what's changed and how we can employ it in our application.

In this article I will guide you through the setup of Dragonfly and explain how to utilize its main features. You will learn how to:

• Integrate Dragonfly into your application
• Configure models to work with Dragonfly
• Introduce a basic uploading mechanism
• Introduce validations
• Generate image thumbnails
• Perform file processing
• Store metadata for uploaded files
• Prepare an application for deployment

To make things more interesting, we are going to create a small musical application. It will present albums and associated songs that can be managed and played back on the website.

The source code for this article is available at GitHub. You can also check out the working demo of the application.

Listing and Managing Albums

To start off, create a new Rails application without the default testing suite:

rails new UploadingWithDragonfly -T

For this article I will be using Rails 5, but most of the described concepts apply to older versions as well.

Creating the Model, Controller, and Routes

Our small musical site is going to contain two models: Album and Song. For now, let's create the first one with the following fields:

• title (string)—contains the album's title
• singer (string)—album's performer
• image_uid (string)—a special field to store the album's preview image. This field can be named anything you like, but it must contain the _uid suffix as instructed by the Dragonfly documentation.

Create and apply the corresponding migration:

rails g model Album title:string singer:string image_uid:string
rails db:migrate

Now let's create a very generic controller to manage albums with all the default actions:

albums_controller.rb

class AlbumsController < ApplicationController
  def index
    @albums = Album.all
  end

  def show
    @album = Album.find(params[:id])
  end

  def new
    @album = Album.new
  end

  def create
    @album = Album.new(album_params)
    if @album.save
      flash[:success] = 'Album added!'
      redirect_to albums_path
    else
      render :new
    end
  end

  def edit
    @album = Album.find(params[:id])
  end

  def update
    @album = Album.find(params[:id])
    if @album.update_attributes(album_params)
      flash[:success] = 'Album updated!'
      redirect_to albums_path
    else
      render :edit
    end
  end

  def destroy
    @album = Album.find(params[:id])
    @album.destroy
    flash[:success] = 'Album removed!'
    redirect_to albums_path
  end

  private

  def album_params
    params.require(:album).permit(:title, :singer)
  end
end

Lastly, add the routes:

config/routes.rb

resources :albums

Integrating Dragonfly

It's time for Dragonfly to step into the limelight. First, add the gem into the Gemfile:

Gemfile

gem 'dragonfly'

Run:

bundle install
rails generate dragonfly

The latter command will create an initializer named dragonfly.rb with the default configuration. We will put it aside for now, but you may read about various options at Dragonfly's official website.

The next important thing to do is equip our model with Dragonfly's methods. This is done by using the dragonfly_accessor:

models/album.rb

dragonfly_accessor :image

Note that here I am saying :image—it directly relates to the image_uid column that we created in the previous section. If you, for example, named your column photo_uid, then the dragonfly_accessor method would need to receive :photo as an argument.

If you are using Rails 4 or 5, another important step is to mark the :image field (not :image_uid!) as permitted in the controller:

albums_controller.rb

params.require(:album).permit(:title, :singer, :image)

This is pretty much it—we are ready to create views and start uploading our files!

Creating Views

Start off with the index view:

views/albums/index.html.erb

<h1>Albums</h1>

<%= link_to 'Add', new_album_path %>

<ul>
  <%= render @albums %>
</ul>

Now the partial:

views/albums/_album.html.erb

<li>
  <%= image_tag(album.image.url, alt: album.title) if album.image_stored? %>
  <%= link_to album.title, album_path(album) %> by
  <%= album.singer %>
  | <%= link_to 'Edit', edit_album_path(album) %>
  | <%= link_to 'Remove', album_path(album), method: :delete, data: {confirm: 'Are you sure?'} %>
</li>

There are two Dragonfly methods to note here:

• album.image.url returns the path to the image.
• album.image_stored? says whether the record has an uploaded file in place.

Now add the new and edit pages:

views/albums/new.html.erb

<h1>Add album</h1>

<%= render 'form' %>

views/albums/edit.html.erb

<h1>Edit <%= @album.title %></h1>

<%= render 'form' %>

views/albums/_form.html.erb

<%= form_for @album do |f| %>
  <div>
    <%= f.label :title %>
    <%= f.text_field :title %>
  </div>

  <div>
    <%= f.label :singer %>
    <%= f.text_field :singer %>
  </div>

  <div>
    <%= f.label :image %>
    <%= f.file_field :image %>
  </div>

  <%= f.submit %>
<% end %>

The form is nothing fancy, but once again note that we are saying :image, not :image_uid, when rendering the file input.

Now you may boot the server and test the uploading feature!

Removing Images

So the users are able to create and edit albums, but there is a problem: they have no way to remove an image, only to replace it with another one. Luckily, this is very easy to fix by introducing a "remove image" checkbox: 

views/albums/_form.html.erb

<% if @album.image_thumb_stored? %>
    <%= image_tag(@album.image.url, alt: @album.title)  %>
    <%= f.label :remove_image %>
    <%= f.check_box :remove_image %>
<% end %>

If the album has an associated image, we display it and render a checkbox. If this checkbox is set, the image will be removed. Note that if your field is named photo_uid, then the corresponding method to remove attachment will be remove_photo. Simple, isn't it?

The only other thing to do is permit the remove_image attribute in your controller:

albums_controller.rb

params.require(:album).permit(:title, :singer, :image, :remove_image)

Adding Validations

At this stage, everything is working fine, but we're not checking the user's input at all, which is not particularly great. Therefore, let's add validations for the Album model:

models/album.rb

validates :title, presence: true
validates :singer, presence: true
validates :image, presence: true
validates_property :width, of: :image, in: (0..900)

validates_property is the Dragonfly method that may check various aspects of your attachment: you may validate a file's extension, MIME type, size, etc.

Now let's create a generic partial to render the errors that were found:

views/shared/_errors.html.erb

<% if object.errors.any? %>
  <div>
    <h4>The following errors were found:</h4>

    <ul>
      <% object.errors.full_messages.each do |msg| %>
        <li><%= msg %></li>
      <% end %>
    </ul>
  </div>
<% end %>

Employ this partial inside the form:

views/albums/_form.html.erb

<%= form_for @album do |f| %>
    <%= render 'shared/errors', object: @album %>
    <%# ... %>
<% end %>

Style the fields with errors a bit to visually depict them:

stylesheets/application.scss

.field_with_errors {
  display: inline;
  label {
    color: red;
  }
  input {
    background-color: lightpink;
  }
}

Retaining an Image Between Requests

Having introduced validations, we run into yet another problem (quite a typical scenario, eh?): if the user has made mistakes while filling in the form, he or she will need to choose the file again after clicking the Submit button.

Dragonfly can help you solve this problem as well by using a retained_* hidden field:

views/albums/_form.html.erb

<%= f.hidden_field :retained_image %>

Don't forget to permit this field as well:

albums_controller.rb

params.require(:album).permit(:title, :singer, :image, :remove_image, :retained_image)

Now the image will be persisted between requests! The only small problem, however, is that the file upload input will still display the "choose a file" message, but this can be fixed with some styling and a dash of JavaScript.

Processing Images

Generating Thumbnails

The images uploaded by our users can have very different dimensions, which can (and probably will) cause a negative impact on the website's design. You probably would like to scale images down to some fixed dimensions, and of course this is possible by utilizing the width and height styles. This is, however, not an optimal approach: the browser will still need to download full-size images and then shrink them.

Another option (which is usually much better) is to generate image thumbnails with some predefined dimensions on the server. This is really simple to achieve with Dragonfly:

views/albums/_album.html.erb

<li>
  <%= image_tag(album.image.thumb('250x250#').url, alt: album.title) if album.image_stored? %>
  <%# ... %>
</li>

250x250 is, of course, the dimensions, whereas # is the geometry that means "resize and crop if necessary to maintain the aspect ratio with center gravity". You may find information about other geometries on Dragonfly's website.

The thumb method is powered by ImageMagick—a great solution for creating and manipulating images. Therefore, in order to see the working demo locally, you'll need to install ImageMagick (all major platforms are supported). 

Support for ImageMagick is enabled by default inside Dragonfly's initializer:

config/initializers/dragonfly.rb

plugin :imagemagick

Now thumbnails are being generated, but they are not stored anywhere. This means each time a user visits the albums page, thumbnails will be regenerated. There are two ways to overcome this problem: by generating them after the record is saved or by performing generation on the fly.

The first option involves introducing a new column to store the thumbnail and tweaking the dragonfly_accessor method. Create and apply a new migration:

rails g migration add_image_thumb_uid_to_albums image_thumb_uid:string
rails db:migrate

Now modify the model:

models/album.rb

dragonfly_accessor :image do
    copy_to(:image_thumb){|a| a.thumb('250x250#') }
end

dragonfly_accessor :image_thumb

Note that now the first call to dragonfly_accessor sends a block that actually generates the thumbnail for us and copies it into the image_thumb. Now just use the image_thumb method in your views:

views/albums/_album.html.erb

<%= image_tag(album.image_thumb.url, alt: album.title) if album.image_thumb_stored? %>

This solution is the simplest, but it's not recommended by the official docs and, what's worse, at the time of writing it does not work with the retained_* fields.

Therefore, let me show you another option: generating thumbnails on the fly. It involves creating a new model and tweaking Dragonfly's config file. First, the model:

rails g model Thumb uid:string job:string
rake db:migrate

The thumbs table will host your thumbnails, but they will be generated on demand. To make this happen, we need to redefine the url method inside the Dragonfly initializer:

config/initializers/dragonfly.rb

Dragonfly.app.configure do
    define_url do |app, job, opts|
        thumb = Thumb.find_by_job(job.signature)
        if thumb
          app.datastore.url_for(thumb.uid, :scheme => 'https')
        else
          app.server.url_for(job)
        end
    end
    
    before_serve do |job, env|
        uid = job.store
        
        Thumb.create!(
            :uid => uid,
            :job => job.signature
        )
    end
    # ...
end

Now add a new album and visit the root page. The first time you do it, the following output will be printed into the logs:

DRAGONFLY: shell command: "convert" "some_path/public/system/dragonfly/development/2017/02/08/3z5p5nvbmx_Folder.jpg" "-resize" "250x250^^" "-gravity" "Center" "-crop" "250x250+0+0" "+repage" "some_path/20170208-1692-1xrqzc9.jpg"

This effectively means that the thumbnail is being generated for us by ImageMagick. If you reload the page, however, this line won't appear anymore, meaning that the thumbnail was cached! You may read a bit more about this feature on Dragonfly's website.

More Processing

You may perform virtually any manipulation to your images after they were uploaded. This can be done inside the after_assign callback. Let's, for example, convert all our images to JPEG format with 90% quality: 

dragonfly_accessor :image do
    after_assign {|a| a.encode!('jpg', '-quality 90') }
end

There are many more actions you can perform: rotate and crop the images, encode with a different format, write text on them, mix with other images (for example, to place a watermark), etc. To see some other examples, refer to the ImageMagick section on the Dragonfly website.

Uploading and Managing Songs

Of course, the main part of our musical site is songs, so let's add them now. Each song has a title and a musical file, and it belongs to an album:

rails g model Song album:belongs_to title:string track_uid:string
rails db:migrate

Hook up the Dragonfly methods, as we did for the Album model:

models/song.rb

dragonfly_accessor :track

Don't forget to establish a has_many relation:

models/album.rb

has_many :songs, dependent: :destroy

Add new routes. A song always exists in the scope of an album, so I'll make these routes nested:

config/routes.rb

resources :albums do
    resources :songs, only: [:new, :create]
end

Create a very simple controller (once again, don't forget to permit the track field):

songs_controller.rb

class SongsController < ApplicationController
  def new
    @album = Album.find(params[:album_id])
    @song = @album.songs.build
  end

  def create
    @album = Album.find(params[:album_id])
    @song = @album.songs.build(song_params)
    if @song.save
      flash[:success] = "Song added!"
      redirect_to album_path(@album)
    else
      render :new
    end
  end

  private

  def song_params
    params.require(:song).permit(:title, :track)
  end
end

Display the songs and a link to add a new one:

views/albums/show.html.erb

<h1><%= @album.title %></h1>
<h2>by <%= @album.singer %></h2>

<%= link_to 'Add song', new_album_song_path(@album) %>

<ol>
  <%= render @album.songs %>
</ol>

Code the form:

views/songs/new.html.erb

<h1>Add song to <%= @album.title %></h1>

<%= form_for [@album, @song] do |f| %>
  <div>
    <%= f.label :title %>
    <%= f.text_field :title %>
  </div>

  <div>
    <%= f.label :track %>
    <%= f.file_field :track %>
  </div>

  <%= f.submit %>
<% end %>

Lastly, add the _song partial:

views/songs/_song.html.erb

<li>
  <%= audio_tag song.track.url, controls: true %>
  <%= song.title %>
</li>

Here I am using the HTML5 audio tag, which will not work for older browsers. So, if you're aiming to support such browsers, use a polyfill.

As you see, the whole process is very straightforward. Dragonfly does not really care what type of file you wish to upload; all in you need to do is provide a dragonfly_accessor method, add a proper field, permit it, and render a file input tag.

Storing Metadata

When I open a playlist, I expect to see some additional information about each song, like its duration or bitrate. Of course, by default this info is not stored anywhere, but we can fix that quite easily. Dragonfly allows us to provide additional data about each uploaded file and fetch it later by using the meta method.

Things, however, are a bit more complex when we are working with audio or video, because to fetch their metadata, a special gem streamio-ffmpeg is needed. This gem, in turn, relies on FFmpeg, so in order to proceed you will need to install it on your PC.

Add streamio-ffmpeg into the Gemfile:

Gemfile

gem 'streamio-ffmpeg'

Install it:

bundle install

Now we can employ the same after_assign callback already seen in the previous sections:

models/song.rb

dragonfly_accessor :track do
    after_assign do |a|
      song = FFMPEG::Movie.new(a.path)
      mm, ss = song.duration.divmod(60).map {|n| n.to_i.to_s.rjust(2, '0')}
      a.meta['duration'] = "#{mm}:#{ss}"
      a.meta['bitrate'] = song.bitrate ? song.bitrate / 1000 : 0
    end
end

Note that here I am using a path method, not url, because at this point we are working with a tempfile. Next we just extract the song's duration (converting it to minutes and seconds with leading zeros) and its bitrate (converting it to kilobytes per second).

Lastly, display metadata in the view:

views/songs/_song.html.erb

<li>
  <%= audio_tag song.track.url, controls: true %>
  <%= song.title %> (<%= song.track.meta['duration'] %>, <%= song.track.meta['bitrate'] %>Kb/s)
</li>

If you check the contents on the public/system/dragonfly folder (the default location to host the uploads), you'll note some .yml files—they are storing all meta information in YAML format.

Deploying to Heroku

The last topic we'll cover today is how to prepare your application before deploying to the Heroku cloud platform. The main problem is that Heroku does not allow you to store custom files (like uploads), so we must rely on a cloud storage service like Amazon S3. Luckily, Dragonfly can be integrated with it easily.

All you need to do is register a new account at AWS (if you don't have it already), create a user with permission to access S3 buckets, and write down the user's key pair in a safe location. You might use a root key pair, but this is really not recommended. Lastly, create an S3 bucket.

Going back to our Rails application, drop in a new gem:  

Gemfile 

group :production do
  gem 'dragonfly-s3_data_store'
end

Install it:

bundle install

Then tweak Dragonfly's configuration to use S3 in a production environment:

config/initializers/dragonfly.rb

if Rails.env.production?
    datastore :s3,
              bucket_name: ENV['S3_BUCKET'],
              access_key_id: ENV['S3_KEY'],
              secret_access_key: ENV['S3_SECRET'],
              region: ENV['S3_REGION'],
              url_scheme: 'https'
else
    datastore :file,
        root_path: Rails.root.join('public/system/dragonfly', Rails.env),
        server_root: Rails.root.join('public')
end

To provide ENV variables on Heroku, use this command:

heroku config:add SOME_KEY=SOME_VALUE

If you wish to test integration with S3 locally, you may use a gem like dotenv-rails to manage environment variables. Remember, however, that your AWS key pair must not be publicly exposed!

Another small issue I've run into while deploying to Heroku was the absence of FFmpeg. The thing is that when a new Heroku application is being created, it has a set of services that are commonly being used (for example, ImageMagick is available by default). Other services can be installed as Heroku addons or in the form of buildpacks. To add an FFmpeg buildpack, run the following command:

heroku buildpacks:add https://github.com/HYPERHYPER/heroku-buildpack-ffmpeg.git

Now everything is ready, and you can share your musical application with the world!

Conclusion

This was a long journey, wasn't it? Today we have discussed Dragonfly—a solution for file uploading in Rails. We have seen its basic setup, some configuration options, thumbnail generation, processing, and metadata storing. Also, we've integrated Dragonfly with the Amazon S3 service and prepared our application for deployment on production.

Of course, we have not discussed all aspects of Dragonfly in this article, so make sure to browse its official website to find extensive documentation and useful examples. If you have any other questions or are stuck with some code examples, don't hesitate to contact me.

Thank you for staying with me, and see you soon!