DEV Community


Rails 5.2 Active Storage: Previews, Poppler, and Solving Licensing Pitfalls

schneems profile image Schneems Originally published at on ・6 min read

Rails 5.2 was just released last month with a major new feature: Active Storage. Active Storage provides file uploads and attachments for Active Record models with a variety of backing services (like AWS S3). While libraries like Paperclip exist to do similar work, this is the first time that such a feature has been shipped with Rails. At Heroku, we consider cloud storage a best practice, so we've ensured that it works on our platform. In this post, we'll share how we prepared for the release of Rails 5.2, and how you can deploy an app today using the new Active Storage functionality.

Trust but Verify

At Heroku, trust is our number one value. When we learned that Active Storage was shipping with Rails 5.2, we began experimenting with all its features. One of the nicest conveniences of Active Storage is its ability to preview PDFs and videos. Instead of linking to assets via text, a small screenshot of the PDF or Video will be extracted from the file and rendered on the page.

The beta version of Rails 5.2 used the popular open source tools FFmpeg and MuPDF to generate video and PDF previews. We vetted these new binary dependencies through both our security and legal departments, where we found that MuPDF licensed under AGPL and requires a commercial license for some use. Had we simply added MuPDF to Rails 5.2+ applications by default, many of our customers would have been unaware that they needed to purchase MuPDF to use it commercially.

The limiting AGPL license was brought to public attention in September 2017. To prepare for the 5.2 release, our engineer Terence Lee worked to update Active Storage so that this PDF preview feature could also use an open-source backend without a commercial license. We opened a PR to Rails introducing the ability to use poppler PDF as an alternative to MuPDF in February of 2018. The PR was merged roughly a month later, and now any Rails 5.2 user - on or off Heroku - can render PDF previews without having to purchase a commercial license.

Active Storage on Heroku Example App

If you've already got an app that implements Active Storage you can jump over to our DevCenter documentation on Active Storage.

Alternatively, you can use our example app. Here is a Rails 5.2 app that is a digital bulletin board allowing people to post videos, pdfs, and images. You can view the source on GitHub or deploy the app with the Heroku button:


Note: This example app requires a paid S3 add-on.

Here's a video example of what the app does.

Active Storage on Heroku

When you open the home page, select an appropriate asset, and then submit the form. In the video, the mp4 file is uploaded to S3 and then a preview is generated on the fly by Rails with the help of ffmpeg. Pretty neat.

Active Storage on Heroku

If you deployed the example app using the button, it's already configured to work on Heroku via the app.json, however if you've got your own app that you would like to deploy, how do you set it up so it works on Heroku?

Following the DevCenter documentation for Active Storage, you will need a file storage service that all your dynos can talk to. The example uses a Heroku add-on for S3 called Bucketeer, though you can also use existing S3 credentials.

To get started, add the AWS gem for S3 to the Gemfile, and if you’re modifying images as well add Mini Magick:

gem "aws-sdk-s3", require: false
gem 'mini_magick', '~> 4.8'

Don't forget to $ bundle install after updating your Gemfile.

Next up, add an amazon option in your config/storage.yml file to point to the S3 config, we are using config set by Bucketeer in this example:

  service: S3
  access_key_id: <%= ENV['BUCKETEER_AWS_ACCESS_KEY_ID'] %>
  secret_access_key: <%= ENV['BUCKETEER_AWS_SECRET_ACCESS_KEY'] %>
  region: <%= ENV['BUCKETEER_AWS_REGION'] %>
  bucket: <%= ENV['BUCKETEER_BUCKET_NAME'] %>

Then make sure that your app is set to use the :amazon config store in production:

config.active_storage.service = :amazon

If you forget this step, the default store is to use :local which saves files to disk. This is not a scalable way to handle uploaded files in production. If you accidentally deploy this to Heroku, it will appear that the files were uploaded at first, but then they will disappear on random requests if you're running more than one dyno. The files will go away altogether when the dynos are restarted. You can get more information about ephemeral disk of Heroku in the DevCenter.

Finally, the last thing you'll need to get this to work in production is to install a custom buildpack that installs the binary dependencies ffmpeg and poppler which are used to generate the asset previews:

$ heroku buildpacks:add -i 1

Once you’re done you can deploy to Heroku!

Adding Active Storage to an Existing App

If your app doesn't already have Active Storage, you can add it. First, you'll need to enable Active Storage blob storage by running:

$ bin/rails active_storage:install

This will add a migration that lets Rails track the uploaded files.

Next, you'll need a model to "attach" files onto. You can use an existing model, or create a new model. In the example app a mostly empty bulletin model is used:

$ bin/rails generate scaffold bulletin

Next, run the migrations on the application:

$ bin/rails db:migrate

After the database is migrated, update the model to let Rails know that you intend to be able to attach files to it:

class Bulletin < ApplicationRecord
  has_one_attached :attachment

Once that's done, we will need three more pieces: a form for uploading attachments, a controller to save attachments, and then a view for rendering the attachments.

If you have an existing form you can add an attachment field via the file_field view helper like this:

<%= form.file_field :attachment %>

You can see an example of a form with an attachment in the example app. Once you have a form, you will need to save the attachment.

In this example app, the home page contains the form and the view. In the bulletin controller the attachment is saved and then the user is redirected back to the main bulletin list:

def create
  @bulletin =

  redirect_back(fallback_location: root_path)

Finally, in the welcome view we iterate through each of the bulletin items and, depending on the type of attachment we have, render it differently.

In Active Storage the previewable? method will return true for PDFs and Videos provided the system has the right binaries installed. The variable? method will return true for images if mini_magick is installed. If neither of these things is true then, the attachment is likely a file that is best viewed after being downloaded. Here's how we can represent that logic:

<ul class="no-bullet">
  <% @bulletin_list.each do |bulletin| %>
      <% if bulletin.attachment.previewable? %>
        <%= link_to(image_tag(bulletin.attachment.preview(resize: "200x200>")), rails_blob_path(bulletin.attachment, disposition: "attachment"))
      <% elsif bulletin.attachment.variable? %>
        <%= link_to(image_tag(bulletin.attachment.variant(resize: "200x200")), rails_blob_path(bulletin.attachment, disposition: "attachment"))%>
      <% else %>
        <%= link_to "Download file", rails_blob_path(bulletin.attachment, disposition: "attachment") %>
      <% end %>
  <% end %>

Once you've got all these pieces in your app, and configured Active Storage to work in production, your users can enjoy uploading and downloading files with ease.


Editor guide
ben profile image
Ben Halpern

I think it's so great for Rails to attempt to evolve and 5.2 has so many niceties.

citizen428 profile image
Michael Kohl

I spent part of my recent talk at RubyConf Taiwan talking about this. Rails is still an excellent choice for a web framework for various reasons:

  1. Language: Ruby is a ton of fun to code in. I started in 2003/04 and still enjoy it tremendously. Yes, it's not the fastest, we all know that. But I always felt like too many people complain about this, without considering that pure request times are only part of a web app. What about optimizing and minimizing markup and CSS? Optimizing images? Using a proper CDN and caching aggressively? HTTP/2? rel="preload" and the loadCSS polyfill? You guys are doing an awesome job here on this site, and a lot of that doesn't come from any framework, but from caring <3
  2. Framework: Rails can't be all bad, otherwise there wouldn't be a Rails inspired framework for almost every language. Plus it's still evolving. Do I agree with every design decision they make? No, of course not. But Rails doesn't get much in your way trying to implement your own architecture on top of it, especially if you include certain modules/follow certain interfaces (i.e. what Ryan Bigg is doing with the rom-rb based ApplicationModel in his "Exploding Rails" book.
  3. Community: The Ruby/Rails communities are pretty great IMHO. They care about things like testing and software architecture, which is why we have so many talks on how to write maintainable Rails apps, or alternative architectures like Trailblazer. And let's not forget the new kids on the block, Roda, Hanami, the dry-rb stack, Hyperloop etc. If there ever was a great time to be a Ruby web developer it's now, on or off the Rails :)

Oops, this got a bit long and I'd still have quite a bit to say, maybe I should turn this comment into a post at one point...