Active Storage Setup for Rails 8

Overview

Active Storage handles file uploads in Rails:

• Cloud storage (S3, GCS, Azure) or local disk
• Image variants (thumbnails, resizing)
• Direct uploads from browser
• Polymorphic attachments

Quick Start

# Install Active Storage (if not already)
bin/rails active_storage:install
bin/rails db:migrate

# Add image processing
bundle add image_processing

Configuration

Storage Services

# config/storage.yml
local:
  service: Disk
  root: <%= Rails.root.join("storage") %>

test:
  service: Disk
  root: <%= Rails.root.join("tmp/storage") %>

amazon:
  service: S3
  access_key_id: <%= Rails.application.credentials.dig(:aws, :access_key_id) %>
  secret_access_key: <%= Rails.application.credentials.dig(:aws, :secret_access_key) %>
  region: eu-west-1
  bucket: <%= Rails.application.credentials.dig(:aws, :bucket) %>

google:
  service: GCS
  credentials: <%= Rails.root.join("config/gcs-credentials.json") %>
  project: my-project
  bucket: my-bucket

Environment Config

# config/environments/development.rb
config.active_storage.service = :local

# config/environments/production.rb
config.active_storage.service = :amazon

Model Attachments

Single Attachment

# app/models/user.rb
class User < ApplicationRecord
  has_one_attached :avatar

  # With variant defaults
  has_one_attached :avatar do |attachable|
    attachable.variant :thumb, resize_to_limit: [100, 100]
    attachable.variant :medium, resize_to_limit: [300, 300]
  end
end

Multiple Attachments

# app/models/event.rb
class Event < ApplicationRecord
  has_many_attached :photos

  has_many_attached :documents do |attachable|
    attachable.variant :preview, resize_to_limit: [200, 200]
  end
end

TDD Workflow

Active Storage Progress:
- [ ] Step 1: Add attachment to model
- [ ] Step 2: Write model spec for attachment
- [ ] Step 3: Add validations (type, size)
- [ ] Step 4: Create upload form
- [ ] Step 5: Handle in controller
- [ ] Step 6: Display in views
- [ ] Step 7: Test upload flow

Testing Attachments

See [testing.md](references/testing.md) for model specs, factory traits, and request specs.

Key patterns:

• Use fixturefileupload in request specs
• Define :with_avatar factory traits using after(:build)
• Test be_attached and variant presence in model specs

Validations

Use the activestoragevalidations gem for declarative validation, or write manual validate methods. See [validations.md](references/validations.md) for both approaches.

# Gemfile
gem 'active_storage_validations'

Image Variants

Define named variants on the model attachment using resizetofill, resizetolimit, or resizetocover. See [variants-and-views.md](references/variants-and-views.md) for variant operations, view helpers, and form examples.

Controller and Service Handling

• Permit :avatar for single uploads, photos: [] for multiple
• Use purge to remove attachments, with optional Turbo Stream response
• Use railsblobpath or send_data for downloads

See [controller-and-service.md](references/controller-and-service.md) for full controller examples, service methods, direct uploads setup, and performance tips.

Checklist

• Active Storage installed and migrated
• Storage service configured
• Image processing gem added (if using variants)
• Attachment added to model
• Validations added (type, size)
• Variants defined
• Controller permits attachment params
• Form handles file upload
• Tests written for attachments
• Direct uploads configured (if needed)

References

• [testing.md](references/testing.md) - Model specs, factory traits, request specs
• [validations.md](references/validations.md) - Gem-based and manual validation examples
• [variants-and-views.md](references/variants-and-views.md) - Variant definitions, view helpers, upload forms
• [controller-and-service.md](references/controller-and-service.md) - Controllers, service methods, direct uploads, performance