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

Schneems - May 10 '18 - - Dev Community

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:

Deploy

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'
Enter fullscreen mode Exit fullscreen mode

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:

amazon:
  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'] %>
Enter fullscreen mode Exit fullscreen mode

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

config.active_storage.service = :amazon
Enter fullscreen mode Exit fullscreen mode

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 https://github.com/heroku/heroku-buildpack-activestorage-preview
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Next, run the migrations on the application:

$ bin/rails db:migrate
Enter fullscreen mode Exit fullscreen mode

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
end
Enter fullscreen mode Exit fullscreen mode

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 %>
Enter fullscreen mode Exit fullscreen mode

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 = Bulletin.new()
  @bulletin.attachment.attach(params[:bulletin][:attachment])
  @bulletin.save!

  redirect_back(fallback_location: root_path)
end
Enter fullscreen mode Exit fullscreen mode

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| %>
    <li>
      <% 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 %>
    </li>
  <% end %>
</ul>
Enter fullscreen mode Exit fullscreen mode

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.

Image
Entenda como o golpe do boleto falso via e-mail ocorre e como se proteger
Image
Transforming Client Relations with AI-Enhanced CRM Solutions

crm, ai, machinelearning, productivity
Image
What is Staff Augmentation? Benefits and Best Practices

management, tutorial, softwareengineering
Image
Discover the Hayati Pro Ultra: A Premium Vaping Experience

hayati, hayatiproultra
Image
What does CORS really do? 🤔

webdev, beginners, programming, security
Image
Using the Open Policy Agent with Backstage!

opensource, opa, backstage, openpolicyagent
Image
Kreowanie Przestrzeni: Sztuka Aranżacji Wnętrz, Która Zmienia Wszystko
Image
How I can run elasticsearch locally for development using docker?

docker, elasticsearch, tutorial
Image
Keuntungan Pilih Situs Judi Online Menurut Ulasan
Image
Trik Simpel Mendapati Keuntungan Dari Bandar Judi Online Sah
Image
What’s the Best and Easiest Way to Embed Data Reporting into My Application? Learn More

embeddedreporting, reportingtools, reporting, dotnet
Image
Bi Fold Door Repairs: What No One Is Talking About
Image
The Ultimate Guide to eWallet App Development Costs in 2024

softwareengineering, softwaredevelopment, programming, development
Image
Ok then let’s find my community 😇
Image
Best VPN Service: 5 VPN Providers That Actually Deliver Results

vpn, bestvpn, topvpn, vpnprovider
Image
FREE Ebook: A Quick Guide to Expert .NET Reporting Tools
Image
Magia mebli: Jak stworzyć przestrzeń, która inspiruje
Image
daya magnet perjudian slots online
Image
My Beginner Journey with Goose: A New Tool for My DevOps Learning Path

goose, beginners, devops, ai
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .