CarrierWave Deployment and Usage Guide

Prerequisites

• Ruby (version 2.7 or higher recommended)
• Rails (version 6.0 or higher for Rails integration) or other Rack-based web framework
• ImageMagick or GraphicsMagick (required for image processing)
• RMagick gem or MiniMagick gem (for image manipulation)
• Fog gem (for cloud storage support)
• ActiveRecord or other supported ORM (for database integration)

Installation

1. Install the gem

gem install carrierwave

2. Add to your Gemfile

gem 'carrierwave', '~> 3.0'

3. Bundle install

bundle install

4. Generate an uploader

rails generate uploader Avatar

This creates app/uploaders/avatar_uploader.rb.

Configuration

1. Configure storage (optional)

Add to your config/initializers/carrierwave.rb:

CarrierWave.configure do |config|
  config.storage = :file  # or :fog for cloud storage
  config.permissions = 0o666
  config.directory_permissions = 0o777
end

2. For cloud storage with Fog

CarrierWave.configure do |config|
  config.fog_credentials = {
    provider: 'AWS',
    aws_access_key_id: ENV['AWS_ACCESS_KEY_ID'],
    aws_secret_access_key: ENV['AWS_SECRET_ACCESS_KEY'],
    region: 'us-east-1'
  }
  config.fog_directory = ENV['AWS_S3_BUCKET']
end

3. Environment variables

Set these in your environment:

• AWS_ACCESS_KEY_ID (for AWS S3)
• AWS_SECRET_ACCESS_KEY (for AWS S3)
• AWS_S3_BUCKET (for AWS S3)
• CARRIERWAVE_STORAGE (optional: file or fog)

Build & Run

1. For Rails applications

Mount the uploader in your model:

class User < ApplicationRecord
  mount_uploader :avatar, AvatarUploader
end

Add the column to your database:

rails g migration add_avatar_to_users avatar:string
rails db:migrate

2. Using the uploader

# In your controller
@user.avatar = params[:file]
@user.save!

# In your views
<%= image_tag @user.avatar.url if @user.avatar.file.present? %>

3. Image processing

Include image processing modules in your uploader:

class AvatarUploader < CarrierWave::Uploader::Base
  include CarrierWave::RMagick  # or CarrierWave::MiniMagick
  
  process :resize_to_fit => [200, 200]
end

Deployment

1. Heroku deployment

# Add buildpack for ImageMagick
heroku buildpacks:add https://github.com/heroku/heroku-buildpack-apt

# Add Aptfile with ImageMagick
echo "imagemagick" > Aptfile

# Deploy
git push heroku main

2. AWS deployment

# Configure AWS S3 credentials
aws configure

# Set environment variables
export AWS_ACCESS_KEY_ID=your_key
export AWS_SECRET_ACCESS_KEY=your_secret
export AWS_S3_BUCKET=your_bucket

3. Docker deployment

FROM ruby:3.1

RUN apt-get update && apt-get install -y imagemagick

WORKDIR /app
COPY Gemfile Gemfile.lock ./
RUN bundle install

COPY . .

CMD ["rails", "server", "-b", "0.0.0.0"]

Troubleshooting

1. "No such file or directory - convert" error

Solution: Install ImageMagick

# Ubuntu/Debian
sudo apt-get install imagemagick

# macOS
brew install imagemagick

2. "undefined method `rmagick!' for CarrierWave::Uploader::Base:Class" error

Solution: Include the correct module in your uploader

class MyUploader < CarrierWave::Uploader::Base
  include CarrierWave::RMagick  # or CarrierWave::MiniMagick
end

3. File permissions issues

Solution: Set proper permissions in your initializer

CarrierWave.configure do |config|
  config.permissions = 0o666
  config.directory_permissions = 0o777
end

4. Cloud storage not working

Solution: Verify your Fog credentials

# Test connection
CarrierWave::Storage::Fog.new(CarrierWave::Uploader::Base.new).connection

5. Memory issues with large images

Solution: Use MiniMagick instead of RMagick

# In your Gemfile
gem 'mini_magick'

# In your uploader
class MyUploader < CarrierWave::Uploader::Base
  include CarrierWave::MiniMagick
end

6. Versioning issues after upgrade

Solution: If upgrading from 2.x to 3.0, recreate versions

@user.avatar.recreate_versions!