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

Generate and apply a new migration:

rails g model Post title:string body:text image:string
rails db:migrate

Set up some routes:

config/routes.rb

resources :posts
root to: 'posts#index'

Also, create a very basic controller:

posts_controller.rb

class PostsController < ApplicationController
  before_action :set_post, only: [:show, :edit, :update]

  def index
    @posts = Post.order('created_at DESC')
  end

  def show
  end

  def new
    @post = Post.new
  end

  def create
    @post = Post.new(post_params)
    if @post.save
      redirect_to posts_path
    else
      render :new
    end
  end

  def edit
  end

  def update
    if @post.update_attributes(post_params)
      redirect_to post_path(@post)
    else
      render :edit
    end
  end

  private

  def post_params
    params.require(:post).permit(:title, :body, :image)
  end

  def set_post
    @post = Post.find(params[:id])
  end
end

Now let's craft the index view:

views/posts/index.html.erb

<h1>Posts</h1>

<%= link_to 'Add post', new_post_path %>

<%= render @posts %>

And the corresponding partial:

views/posts/_post.html.erb

<h2><%= link_to post.title, post_path(post) %></h2>

<p><%= truncate(post.body, length: 150) %></p>

<p><%= link_to 'Edit', edit_post_path(post) %></p>
<hr>

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 uploaders that 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:

views/posts/new.html.erb

<h1>Add post</h1>

<%= render 'form', post: @post %>

views/posts/_form.html.erb

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

  <div>
    <%= f.label :body %>
    <%= f.text_area :body %>
  </div>

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

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

Note that the PostsController does not need to be modified as we already permitted the image attribute.

Lastly, create the edit view:

views/posts/edit.html.erb

<h1>Edit post</h1>

<%= render 'form', post: @post %>

That's it! You may boot the server and try to create a post with an image. The problem is that this image is not visible anywhere, so let's proceed to the next section and add a show page!

Displaying Images

So, the only view we have not created yet is show. Add it now:

views/posts/show.html.erb

<%= link_to 'All posts', posts_path %>
<h1><%= @post.title %></h1>

<%= image_tag(@post.image.url, alt: 'Image') if @post.image? %>

<p><%= @post.body %></p>

<p><%= link_to 'Edit', edit_post_path(@post) %></p>

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:

rails c
Post.find_each {|post| post.image.recreate_versions!(:thumb) if post.image?}

Lastly, display your thumbnail with a link to the original image:

views/posts/show.html.erb

<%= link_to(image_tag(@post.image.thumb.url, alt: 'Image'), @post.image.url, target: '_blank') if @post.image? %>

Boot the server and observe the result!

Adding Validations

Currently our uploading works, but we're not validating user input at all, which is, of course, bad. As long as we want to work only with images, let's whitelist .png, .jpg and .gif extensions:

uploaders/image_uploader.rb

def extension_whitelist
    %w(jpg jpeg gif png)
end

You may also add content type checks by defining a content_type_whitelist method:

uploaders/image_uploader.rb

def content_type_whitelist
    /image\//
end

Alternatively, it is possible to blacklist some file types, for example executables, by defining the content_type_blacklist method.

Apart from checking a file's type and extension, let's enforce it to be less than 1 megabyte. To do it, we'll require an additional gem supporting file validations for ActiveModel:

Gemfile

gem 'file_validators'

Install it:

bundle install

Now introduce the desired validations (note that I am also adding checks for the title and body attributes):

models/post.rb

validates :title, presence: true, length: {minimum: 2}
validates :body, presence: true
validates :image, file_size: { less_than: 1.megabytes }

The next thing to do is to add I18n translations for Carrierwave's error messages:

config/locales/en.yml

en:
  errors:
    messages:
      carrierwave_processing_error: "Cannot resize image."
      carrierwave_integrity_error: "Not an image."
      carrierwave_download_error: "Couldn't download image."
      extension_whitelist_error: "You are not allowed to upload %{extension} files, allowed types: %{allowed_types}"
      extension_blacklist_error: "You are not allowed to upload %{extension} files, prohibited types: %{prohibited_types}"

Currently, we do not display validation errors anywhere, so let's create a shared partial:

views/shared/_errors.html.erb

<% if object.errors.any? %>
  <h3>Some errors were found:</h3>
  <ul>
    <% object.errors.full_messages.each do |message| %>
      <li><%= message %></li>
    <% end %>
  </ul>
<% end %>

Employ this partial inside the form:

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.

Persisting Files Across Requests

Persisting files across form redisplays is actually quite easy. All you need to do is add a new hidden field and permit it inside the controller:

views/shared/_form.html.erb

<%= f.label :image %>
<%= f.file_field :image %><br>
<%= f.hidden_field :image_cache %>

posts_controller.rb

params.require(:post).permit(:title, :body, :image, :image_cache)

Now the image_cache will be populated automatically and the image won't be lost. It may be helpful to display a thumbnail as well so that user understands the image was processed successfully: 

views/shared/_form.html.erb

<% if post.image? %>
    <%= image_tag post.image.thumb.url %>
<% end %>

Removing Images

Another very common feature is the ability to remove attached files when editing a record. With Carrierwave, implementing this feature is not a problem. Add a new checkbox to the form:

views/shared/_form.html.erb

<% if post.image? %>
    <%= image_tag post.image.thumb.url %>
    <div>
      <%= label_tag :remove_image do %>
        Remove image
        <%= f.check_box :remove_image %>
      <% end %>
    </div>
<% end %>

And permit the remove_image attribute:

posts_controller.rb

params.require(:post).permit(:title, :body, :image, :remove_image, :image_cache)

That's it! To remove an image manually, use the remove_image! method:

@post.remove_image!

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

<%= f.text_field :remote_image_url %>
<small>Enter URL to an image</small>

posts_controller.rb

params.require(:post).permit(:title, :body, :image, :remove_image, :image_cache, :remote_image_url)

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:

Gemfile

gem 'pg'

Install it:

bundle install

Modify the database configuration like this:

config/database.yml

default: &default
  adapter: postgresql
  pool: 5
  timeout: 5000

development:
  <<: *default
  database: upload_carrier_dev
  username: 'YOUR_USER'
  password: 'YOUR_PASSWORD'
  host: localhost

Create the corresponding Postgres database, and then generate and apply the migration:

rails g migration add_attachments_to_posts attachments:json
rails db:migrate

If you prefer to stick with SQLite, follow the instructions listed in Carrierwave's documentation.

Now mount the uploaders (note the plural form!):

model/post.rb

mount_uploaders :attachments, ImageUploader

I am using the same uploader for attachments, but of course you can generate a new one with a different configuration.

Add the multiple file field to your form:

views/shared/_form.html.erb

<div>
    <%= f.label :attachments %>
    <%= f.file_field :attachments, multiple: true %>
</div>

As long as the attachments field is going to contain an array, it should be permitted in the following way:

posts_controller.rb

params.require(:post).permit(:title, :body, :image, :remove_image, :image_cache, :remote_image_url, attachments: [])

Lastly, you may iterate over the post's attachments and display them as usual:

views/shared/show.html.erb

<% if @post.attachments? %>
  <ul>
    <% @post.attachments.each do |attachment| %>
      <li><%= link_to(image_tag(attachment.thumb.url, alt: 'Image'), attachment.url, target: '_blank') %></li>
    <% end %>
  </ul>
<% end %>

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:

config/initializers/carrierwave.rb

CarrierWave.configure do |config|
  config.fog_provider = 'fog/aws'
  config.fog_credentials = {
      provider:              'AWS',
      aws_access_key_id:     ENV['S3_KEY'],
      aws_secret_access_key: ENV['S3_SECRET'],
      region:                ENV['S3_REGION'],
  }
  config.fog_directory  = ENV['S3_BUCKET']
end

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.

So I thank you for staying with me, and happy coding!