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 for model specs, factory traits, and request specs.

Key patterns:

• Use fixture_file_upload in request specs

• Define :with_avatar factory traits using after(:build)

• Test be_attached and variant presence in model specs

Validations

Use the active_storage_validations gem for declarative validation, or write manual validate methods. See validations.md for both approaches.

Gemfile

gem 'active_storage_validations'

Image Variants

Define named variants on the model attachment using resize_to_fill , resize_to_limit , or resize_to_cover . See 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 rails_blob_path or send_data for downloads

See 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 - Model specs, factory traits, request specs

• validations.md - Gem-based and manual validation examples

• variants-and-views.md - Variant definitions, view helpers, upload forms

• controller-and-service.md - Controllers, service methods, direct uploads, performance