Uploading With Rails and Carrierwave

Uploading With Rails and Carrierwave

This is another article in the "Uploading with Rails" series. Today we are going to meet Carrierwave—one of the most popular file uploading solutions for Rails. I like Carrierwave because it is easy to get started, it has lots of features out of the box, and it provides dozens of "how to" articles written by the members of the community, so you won't get lost.

In this article, you will learn how to:

Integrate Carrierwave into your Rails app

Add validations

Persist files across requests

Remove files

Generate thumbnails

Upload files from remote locations

Introduce multiple file uploads

Add support for cloud storage

The source code for this article is available on GitHub. Enjoy reading!

Laying the Foundations

As always, start by creating a new Rails application:

rails new UploadingWithCarrierwave -T

For this demo I'll be using Rails 5.0.2. Please note that Carrierwave 1 supports only Rails 4+ and Ruby 2. If you are still riding on Rails 3, then hook up Carrierwave version 0.11.

To see Carrierwave in action, we are going to create a very simple blogging application with a sole Post model. It will have the following main attributes:

title (string)

body (text)

image (string)—this field is going to contain an image (a file's name, to be precise) attached to the post

views/posts/_post.html.erb

Here I am using the Rails truncate method to display only the first 150 symbols from the post. Before we create other views and a form partial, let's firstly integrate Carrierwave into the application.

Integrating Carrierwave

Drop in a new gem into the Gemfile:

Gemfile

gem 'carrierwave', '~> 1.0'

Run:

bundle install

Carrierwave stores its configuration inside uploadersthat are included into your models. To generate an uploader, use the following command:

rails generate uploader Image

Now, inside app/uploaders, you will find a new file called image_uploader.rb. Note that it has some useful comments and examples, so you may use it to get started. In this demo we will use ActiveRecord, but Carrierwave also has support for Mongoid, Sequel, and DataMapper.

Next, we need to include or mount this uploader into the model:

models/post.rb

mount_uploader :image, ImageUploader

The uploader already has sane default settings, but at the very least we need to choose where the uploaded files will be stored. For now, let's employ file storage:

uploaders/image_uploader.rb

storage :file

By default, files will be placed inside the public/uploads directory, so it is best to exclude it from the version control system:

.gitignore

public/uploads

You may also modify the store_dir method inside your uploader to choose some other location.

At this point, we can create a new view and a form partial to start uploading files:

As you can see, displaying an attachment is really easy: all you need to do is say @post.image.url to grab an image's URL. To get a path to the file, use the current_path method. Note that Carrierwave also provides an image? method for us to check whether an attachment is present at all (the image method itself will never return nil, even if the file is not present).

Now, after navigating to a post, you should see an image, but it might appear too big: after all, we are not restricting dimensions anywhere. Of course, we could have scaled the image down with some CSS rules, but it is much better to generate a thumbnail after the file has been uploaded. This, however, requires some additional steps.

Generating Thumbnails

In order to crop and scale images, we need a separate tool. Out of the box Carrierwave has support for RMagick and MiniMagick gems that, in turn, are used to manipulate images with the help of ImageMagick. ImageMagick is an open-source solution allowing you to edit existing images and generate new ones, so before proceeding you need to download and install it. Next, you are free to pick either of the two gems. I'll stick with MiniMagick, because it is much easier to install and it has better support:

Gemfile

gem 'mini_magick'

Run:

bundle install

Then include MiniMagick into your uploader:

uploaders/image_uploader.rb

include CarrierWave::MiniMagick

Now we simply need to introduce a new version to our uploader. The concept of versions (or styles) is used in many file uploading libraries; it simply means that additional files based on the original attachment will be created with, for example, different dimensions or formats. Introduce a new version called thumb:

uploaders/image_uploader.rb

version :thumb do
process resize_to_fill: [350, 350]
end

You may have as many versions as you like and, what's more, versions can even be built on top of other ones:

uploaders/image_uploader.rb

version :small_thumb, from_version: :thumb do
process resize_to_fill: [20, 20]
end

If you have already uploaded some images, they won't have thumbnails available. This is not a problem, though, as you can re-create them from the Rails console:

views/posts/_form.html.erb

<%= render 'shared/errors', object: post %>

Now try to upload some invalid files and observe the result. It should work, but if you choose a valid file and do not fill in the title or body, then the checks will still fail and an error will be displayed. However, the file field will be cleared out and the user will need to choose the image again, which is not very convenient. To fix it, we need to add another field to the form.

posts_controller.rb

Uploading From a Remote Location

Carrierwave also provides a very cool feature out of the box: the ability to upload files from remote locations by their URL. Let's introduce this ability now by adding a new field and permitting the corresponding attribute:

views/shared/_form.html.erb

posts_controller.rb

How cool is that? You don't need to make any changes at all, and you can test this feature right away!

Working With Multiple Uploads

Suppose we want our post to have multiple attachments available. With the current setup it is not possible, but luckily, Carrierwave supports such a scenario as well. To implement this feature, you need to add either a serialized field (for SQLite) or a JSON field (for Postgres or MySQL). I prefer the latter option, so let's switch to a new database adapter now. Remove the sqlite3 gem from the Gemfile and add pg instead:

Note that each attachment is going to have a thumbnail as configured in our ImageUploader. Nice!

Using Cloud Storage

Sticking with file storage is not always convenient and/or possible as, for example, on Heroku it is not possible to store custom files. Therefore you might ask how to marry Carrierwave with Amazon S3 cloud storage? Well, that's a pretty easy task as well. Carrierwave depends on the fog-aws gem to implement this feature:

Gemfile

gem "fog-aws"

Install it:

bundle install

Let's create an initializer for Carrierwave and configure the cloud storage globally:

There are some other options available, which can be found in the documentation.

I am using the dotenv-rails gem to set the environment variables in a secure way, but you may choose any other option. However, make sure that your S3 key pair is not available publicly, because otherwise anyone can upload anything to your bucket!

Next, replace the storage :file line with:

uploaders/image_uploader.rb

storage :fog

Apart from S3, Carrierwave supports uploads to Google Storage and Rackspace. These services are easy to set up as well.

Conclusion

This is it for today! We have covered all the major features of Carrierwave, and now you can start using it in your projects. It has some additional options available, so do browse the documentation.

If you are stuck, don't hesitate to post your questions. Also, it might be useful to take a peek into Carrierwave's wiki, which hosts useful "how to" articles answering many common questions.