CINXE.COM

<!doctype html> <html dir="ltr" lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>Active Storage Overview — Ruby on Rails Guides</title> <link rel="stylesheet" type="text/css" href="stylesheets/style-071e355820fc155a5c40ef8a1c0c4971.css" data-turbo-track="reload"> <link rel="stylesheet" type="text/css" href="stylesheets/print-a87ee66d50ce96bb83ac082f1249fe3e.css" media="print"> <link rel="stylesheet" type="text/css" href="stylesheets/highlight-a0d2133dd0073968b2d33b1f1360a2a3.css" data-turbo-track="reload"> <link rel="icon" href="images/favicon.ico" sizes="any"> <link rel="apple-touch-icon" href="images/icon.png"> <script src="javascripts/@hotwired--turbo-764f59c7edbeb902a9068c0340dd274e.js" data-turbo-track="reload"></script> <script src="javascripts/clipboard-8b7aed6f069f0cf58eeae353cd2f898b.js" data-turbo-track="reload"></script> <script src="javascripts/guides-897790ae3777ddd81bd4953f7ec99835.js" data-turbo-track="reload"></script> <meta property="og:title" content="Active Storage Overview — Ruby on Rails Guides" /> <meta name="description" content="Active Storage OverviewThis guide covers how to attach files to your Active Record models.After reading this guide, you will know: How to attach one or many files to a record. How to delete an attached file. How to link to an attached file. How to use variants to transform images. How to generate an image representation of a non-image file, such as a PDF or a video. How to send file uploads directly from browsers to a storage service, bypassing your application servers. How to clean up files stored during testing. How to implement support for additional storage services." /> <meta property="og:description" content="Active Storage OverviewThis guide covers how to attach files to your Active Record models.After reading this guide, you will know: How to attach one or many files to a record. How to delete an attached file. How to link to an attached file. How to use variants to transform images. How to generate an image representation of a non-image file, such as a PDF or a video. How to send file uploads directly from browsers to a storage service, bypassing your application servers. How to clean up files stored during testing. How to implement support for additional storage services." /> <meta property="og:locale" content="en_US" /> <meta property="og:site_name" content="Ruby on Rails Guides" /> <meta property="og:image" content="https://avatars.githubusercontent.com/u/4223" /> <meta property="og:type" content="website" /> <link rel="preconnect" href="https://fonts.googleapis.com"> <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin> <link href="https://fonts.googleapis.com/css2?family=Noto+Sans+Arabic:wght@100..900&display=swap" rel="stylesheet"> <link href="https://fonts.googleapis.com/css2?family=Heebo:wght@100..900&family=Noto+Sans+Arabic:wght@100..900&display=swap" rel="stylesheet"> <meta name="theme-color" content="#C81418"> </head> <body dir="ltr" class="guide no-js"> <script> document.body.classList.remove('no-js') </script> <a id="main-skip-link" href="#main" class="skip-link" data-turbo="false"> Skip to main content </a> <div id="mobile-navigation-bar"> <div class="wrapper"> More at <a href="https://rubyonrails.org/">rubyonrails.org:</a> <button type="button" class="js-only red-button more-info-button" id="more-info" aria-controls="more-info-links" aria-expanded="false"> More Ruby on Rails </button> <ul id="more-info-links" class="more-info-links hidden"> <li class="more-info"><a href="https://rubyonrails.org/blog">Blog</a></li> <li class="more-info"><a href="https://guides.rubyonrails.org/">Guides</a></li> <li class="more-info"><a href="https://api.rubyonrails.org/">API</a></li> <li class="more-info"><a href="https://discuss.rubyonrails.org/">Forum</a></li> <li class="more-info"><a href="https://github.com/rails/rails">Contribute on GitHub</a></li> </ul> </div> </div> <header id="page-header"> <div class="wrapper clearfix"> <nav id="feature-nav"> <div class="header-logo"> <a href="index.html" title="Guides home for v8.0.0 Guides">Guides</a> <label for="version-switcher-select">Version: pick from the list to go to that Rails version's guides</label> <select id="version-switcher-select" class="guides-version"> <option value="https://edgeguides.rubyonrails.org/">Edge</option> <option value="https://guides.rubyonrails.org/v8.0/" selected>8.0</option> <option value="https://guides.rubyonrails.org/v7.2/">7.2</option> <option value="https://guides.rubyonrails.org/v7.1/">7.1</option> <option value="https://guides.rubyonrails.org/v7.0/">7.0</option> <option value="https://guides.rubyonrails.org/v6.1/">6.1</option> <option value="https://guides.rubyonrails.org/v6.0/">6.0</option> <option value="https://guides.rubyonrails.org/v5.2/">5.2</option> <option value="https://guides.rubyonrails.org/v5.1/">5.1</option> <option value="https://guides.rubyonrails.org/v5.0/">5.0</option> <option value="https://guides.rubyonrails.org/v4.2/">4.2</option> <option value="https://guides.rubyonrails.org/v4.1/">4.1</option> <option value="https://guides.rubyonrails.org/v4.0/">4.0</option> <option value="https://guides.rubyonrails.org/v3.2/">3.2</option> <option value="https://guides.rubyonrails.org/v3.1/">3.1</option> <option value="https://guides.rubyonrails.org/v3.0/">3.0</option> <option value="https://guides.rubyonrails.org/v2.3/">2.3</option> </select> </div> <ul class="nav"> <li><a class="nav-item" id="home_nav" href="https://rubyonrails.org/">Home</a></li> <li class="guides-index guides-index-large"> <a href="index.html" id="guides-menu-button" data-aria-controls="guides" data-aria-expanded="false" class="guides-index-item nav-item">Guides Index</a> <div id="guides" class="clearfix" style="display: none;"> <hr /> <dl class="guides-section-container"> <div class="guides-section"> <dt>Start Here</dt> <dd><a href="getting_started.html">Getting Started with Rails</a></dd> </div> <div class="guides-section"> <dt>Models</dt> <dd><a href="active_record_basics.html">Active Record Basics</a></dd> <dd><a href="active_record_migrations.html">Active Record Migrations</a></dd> <dd><a href="active_record_validations.html">Active Record Validations</a></dd> <dd><a href="active_record_callbacks.html">Active Record Callbacks</a></dd> <dd><a href="association_basics.html">Active Record Associations</a></dd> <dd><a href="active_record_querying.html">Active Record Query Interface</a></dd> <dd><a href="active_model_basics.html">Active Model Basics</a></dd> </div> <div class="guides-section"> <dt>Views</dt> <dd><a href="action_view_overview.html">Action View Overview</a></dd> <dd><a href="layouts_and_rendering.html">Layouts and Rendering in Rails</a></dd> <dd><a href="action_view_helpers.html">Action View Helpers</a></dd> <dd><a href="form_helpers.html">Action View Form Helpers</a></dd> </div> <div class="guides-section"> <dt>Controllers</dt> <dd><a href="action_controller_overview.html">Action Controller Overview</a></dd> <dd><a href="routing.html">Rails Routing from the Outside In</a></dd> </div> <div class="guides-section"> <dt>Other Components</dt> <dd><a href="active_support_core_extensions.html">Active Support Core Extensions</a></dd> <dd><a href="action_mailer_basics.html">Action Mailer Basics</a></dd> <dd><a href="action_mailbox_basics.html">Action Mailbox Basics</a></dd> <dd><a href="action_text_overview.html">Action Text Overview</a></dd> <dd><a href="active_job_basics.html">Active Job Basics</a></dd> <dd><a href="active_storage_overview.html">Active Storage Overview</a></dd> <dd><a href="action_cable_overview.html">Action Cable Overview</a></dd> </div> <div class="guides-section"> <dt>Digging Deeper</dt> <dd><a href="i18n.html">Rails Internationalization (I18n) API</a></dd> <dd><a href="testing.html">Testing Rails Applications</a></dd> <dd><a href="security.html">Securing Rails Applications</a></dd> <dd><a href="error_reporting.html">Error Reporting in Rails Applications</a></dd> <dd><a href="debugging_rails_applications.html">Debugging Rails Applications</a></dd> <dd><a href="configuring.html">Configuring Rails Applications</a></dd> <dd><a href="command_line.html">The Rails Command Line</a></dd> <dd><a href="asset_pipeline.html">The Asset Pipeline</a></dd> <dd><a href="working_with_javascript_in_rails.html">Working with JavaScript in Rails</a></dd> <dd><a href="autoloading_and_reloading_constants.html">Autoloading and Reloading</a></dd> <dd><a href="caching_with_rails.html">Caching with Rails: An Overview</a></dd> <dd><a href="api_app.html">Using Rails for API-only Applications</a></dd> <dd><a href="tuning_performance_for_deployment.html">Tuning Performance for Deployment</a></dd> </div> <div class="guides-section"> <dt>Advanced Active Record</dt> <dd><a href="active_record_multiple_databases.html">Multiple Databases</a></dd> <dd><a href="active_record_composite_primary_keys.html">Composite Primary Keys</a></dd> </div> <div class="guides-section"> <dt>Extending Rails</dt> <dd><a href="rails_on_rack.html">Rails on Rack</a></dd> <dd><a href="generators.html">Creating and Customizing Rails Generators & Templates</a></dd> </div> <div class="guides-section"> <dt>Contributing</dt> <dd><a href="contributing_to_ruby_on_rails.html">Contributing to Ruby on Rails</a></dd> <dd><a href="api_documentation_guidelines.html">API Documentation Guidelines</a></dd> <dd><a href="ruby_on_rails_guides_guidelines.html">Guides Guidelines</a></dd> <dd><a href="development_dependencies_install.html">Installing Rails Core Development Dependencies</a></dd> </div> <div class="guides-section"> <dt>Policies</dt> <dd><a href="maintenance_policy.html">Maintenance Policy</a></dd> </div> <div class="guides-section"> <dt>Release Notes</dt> <dd><a href="upgrading_ruby_on_rails.html">Upgrading Ruby on Rails</a></dd> <dd><a href="7_2_release_notes.html">Version 7.2 - August 2024</a></dd> <dd><a href="7_1_release_notes.html">Version 7.1 - October 2023</a></dd> <dd><a href="7_0_release_notes.html">Version 7.0 - December 2021</a></dd> <dd><a href="6_1_release_notes.html">Version 6.1 - December 2020</a></dd> <dd><a href="6_0_release_notes.html">Version 6.0 - August 2019</a></dd> <dd><a href="5_2_release_notes.html">Version 5.2 - April 2018</a></dd> <dd><a href="5_1_release_notes.html">Version 5.1 - April 2017</a></dd> <dd><a href="5_0_release_notes.html">Version 5.0 - June 2016</a></dd> <dd><a href="4_2_release_notes.html">Version 4.2 - December 2014</a></dd> <dd><a href="4_1_release_notes.html">Version 4.1 - April 2014</a></dd> <dd><a href="4_0_release_notes.html">Version 4.0 - June 2013</a></dd> <dd><a href="3_2_release_notes.html">Version 3.2 - January 2012</a></dd> <dd><a href="3_1_release_notes.html">Version 3.1 - August 2011</a></dd> <dd><a href="3_0_release_notes.html">Version 3.0 - August 2010</a></dd> <dd><a href="2_3_release_notes.html">Version 2.3 - March 2009</a></dd> <dd><a href="2_2_release_notes.html">Version 2.2 - November 2008</a></dd> </div> </dl> </div> </li> <li><a class="nav-item" href="contributing_to_ruby_on_rails.html">Contribute</a></li> <li class="guides-index guides-index-small js-only"> <label for="guides-selector"> Navigate to a guide: </label> <select id="guides-selector" class="guides-index-item nav-item"> <option value="index.html">Guides Index</option> <optgroup label="Start Here"> <option value="getting_started.html">Getting Started with Rails</option> </optgroup> <optgroup label="Models"> <option value="active_record_basics.html">Active Record Basics</option> <option value="active_record_migrations.html">Active Record Migrations</option> <option value="active_record_validations.html">Active Record Validations</option> <option value="active_record_callbacks.html">Active Record Callbacks</option> <option value="association_basics.html">Active Record Associations</option> <option value="active_record_querying.html">Active Record Query Interface</option> <option value="active_model_basics.html">Active Model Basics</option> </optgroup> <optgroup label="Views"> <option value="action_view_overview.html">Action View Overview</option> <option value="layouts_and_rendering.html">Layouts and Rendering in Rails</option> <option value="action_view_helpers.html">Action View Helpers</option> <option value="form_helpers.html">Action View Form Helpers</option> </optgroup> <optgroup label="Controllers"> <option value="action_controller_overview.html">Action Controller Overview</option> <option value="routing.html">Rails Routing from the Outside In</option> </optgroup> <optgroup label="Other Components"> <option value="active_support_core_extensions.html">Active Support Core Extensions</option> <option value="action_mailer_basics.html">Action Mailer Basics</option> <option value="action_mailbox_basics.html">Action Mailbox Basics</option> <option value="action_text_overview.html">Action Text Overview</option> <option value="active_job_basics.html">Active Job Basics</option> <option value="active_storage_overview.html">Active Storage Overview</option> <option value="action_cable_overview.html">Action Cable Overview</option> </optgroup> <optgroup label="Digging Deeper"> <option value="i18n.html">Rails Internationalization (I18n) API</option> <option value="testing.html">Testing Rails Applications</option> <option value="security.html">Securing Rails Applications</option> <option value="error_reporting.html">Error Reporting in Rails Applications</option> <option value="debugging_rails_applications.html">Debugging Rails Applications</option> <option value="configuring.html">Configuring Rails Applications</option> <option value="command_line.html">The Rails Command Line</option> <option value="asset_pipeline.html">The Asset Pipeline</option> <option value="working_with_javascript_in_rails.html">Working with JavaScript in Rails</option> <option value="autoloading_and_reloading_constants.html">Autoloading and Reloading</option> <option value="caching_with_rails.html">Caching with Rails: An Overview</option> <option value="api_app.html">Using Rails for API-only Applications</option> <option value="tuning_performance_for_deployment.html">Tuning Performance for Deployment</option> </optgroup> <optgroup label="Advanced Active Record"> <option value="active_record_multiple_databases.html">Multiple Databases</option> <option value="active_record_composite_primary_keys.html">Composite Primary Keys</option> </optgroup> <optgroup label="Extending Rails"> <option value="rails_on_rack.html">Rails on Rack</option> <option value="generators.html">Creating and Customizing Rails Generators & Templates</option> </optgroup> <optgroup label="Contributing"> <option value="contributing_to_ruby_on_rails.html">Contributing to Ruby on Rails</option> <option value="api_documentation_guidelines.html">API Documentation Guidelines</option> <option value="ruby_on_rails_guides_guidelines.html">Guides Guidelines</option> <option value="development_dependencies_install.html">Installing Rails Core Development Dependencies</option> </optgroup> <optgroup label="Policies"> <option value="maintenance_policy.html">Maintenance Policy</option> </optgroup> <optgroup label="Release Notes"> <option value="upgrading_ruby_on_rails.html">Upgrading Ruby on Rails</option> <option value="7_2_release_notes.html">Version 7.2 - August 2024</option> <option value="7_1_release_notes.html">Version 7.1 - October 2023</option> <option value="7_0_release_notes.html">Version 7.0 - December 2021</option> <option value="6_1_release_notes.html">Version 6.1 - December 2020</option> <option value="6_0_release_notes.html">Version 6.0 - August 2019</option> <option value="5_2_release_notes.html">Version 5.2 - April 2018</option> <option value="5_1_release_notes.html">Version 5.1 - April 2017</option> <option value="5_0_release_notes.html">Version 5.0 - June 2016</option> <option value="4_2_release_notes.html">Version 4.2 - December 2014</option> <option value="4_1_release_notes.html">Version 4.1 - April 2014</option> <option value="4_0_release_notes.html">Version 4.0 - June 2013</option> <option value="3_2_release_notes.html">Version 3.2 - January 2012</option> <option value="3_1_release_notes.html">Version 3.1 - August 2011</option> <option value="3_0_release_notes.html">Version 3.0 - August 2010</option> <option value="2_3_release_notes.html">Version 2.3 - March 2009</option> <option value="2_2_release_notes.html">Version 2.2 - November 2008</option> </optgroup> </select> </li> </ul> </nav> </div> </header> <hr class="hide" /> <main id="main"> <article> <header id="feature"> <div class="wrapper"> <h1>Active Storage Overview</h1>This guide covers how to attach files to your Active Record models.After reading this guide, you will know: <ul> <li>How to attach one or many files to a record.</li> <li>How to delete an attached file.</li> <li>How to link to an attached file.</li> <li>How to use variants to transform images.</li> <li>How to generate an image representation of a non-image file, such as a PDF or a video.</li> <li>How to send file uploads directly from browsers to a storage service, bypassing your application servers.</li> <li>How to clean up files stored during testing.</li> <li>How to implement support for additional storage services.</li> </ul> <nav id="column-side" aria-label="Chapter" class="guide-index" data-turbo="false"> <a id="chapter-nav-skip-link" href="#article-body" class="skip-link"> Skip to article body </a> <h2 class="chapter"> <picture aria-hidden="true">  <source srcset="images/icon_book-close-bookmark-1-wht.svg" media="(prefers-color-scheme: dark)" /> <img src="images/icon_book-close-bookmark-1.svg" alt="Chapter Icon" /> </picture> Chapters </h2> <ol class="chapters"> <li><a href="#what-is-active-storage-questionmark">What is Active Storage?</a> <ul> <li><a href="#requirements">Requirements</a></li> </ul></li> <li><a href="#setup">Setup</a> <ul> <li><a href="#disk-service">Disk Service</a></li> <li><a href="#s3-service-amazon-s3-and-s3-compatible-apis">S3 Service (Amazon S3 and S3-compatible APIs)</a></li> <li><a href="#microsoft-azure-storage-service">Microsoft Azure Storage Service</a></li> <li><a href="#google-cloud-storage-service">Google Cloud Storage Service</a></li> <li><a href="#mirror-service">Mirror Service</a></li> <li><a href="#public-access">Public access</a></li> </ul></li> <li><a href="#attaching-files-to-records">Attaching Files to Records</a> <ul> <li><a href="#has-one-attached"><code>has_one_attached</code></a></li> <li><a href="#has-many-attached"><code>has_many_attached</code></a></li> <li><a href="#attaching-file-io-objects">Attaching File/IO Objects</a></li> <li><a href="#replacing-vs-adding-attachments">Replacing vs Adding Attachments</a></li> <li><a href="#form-validation">Form Validation</a></li> </ul></li> <li><a href="#removing-files">Removing Files</a></li> <li><a href="#serving-files">Serving Files</a> <ul> <li><a href="#redirect-mode">Redirect Mode</a></li> <li><a href="#proxy-mode">Proxy Mode</a></li> <li><a href="#authenticated-controllers">Authenticated Controllers</a></li> </ul></li> <li><a href="#downloading-files">Downloading Files</a></li> <li><a href="#analyzing-files">Analyzing Files</a></li> <li><a href="#displaying-images-videos-and-pdfs">Displaying Images, Videos, and PDFs</a> <ul> <li><a href="#lazy-vs-immediate-loading">Lazy vs Immediate Loading</a></li> <li><a href="#transforming-images">Transforming Images</a></li> <li><a href="#previewing-files">Previewing Files</a></li> </ul></li> <li><a href="#direct-uploads">Direct Uploads</a> <ul> <li><a href="#usage">Usage</a></li> <li><a href="#cross-origin-resource-sharing-cors-configuration">Cross-Origin Resource Sharing (CORS) Configuration</a></li> <li><a href="#direct-upload-javascript-events">Direct Upload JavaScript Events</a></li> <li><a href="#example">Example</a></li> <li><a href="#custom-drag-and-drop-solutions">Custom drag and drop solutions</a></li> <li><a href="#track-the-progress-of-the-file-upload">Track the progress of the file upload</a></li> <li><a href="#integrating-with-libraries-or-frameworks">Integrating with Libraries or Frameworks</a></li> </ul></li> <li><a href="#testing">Testing</a> <ul> <li><a href="#discarding-files-created-during-tests">Discarding Files Created During Tests</a></li> <li><a href="#adding-attachments-to-fixtures">Adding Attachments to Fixtures</a></li> <li><a href="#configuring-services">Configuring services</a></li> </ul></li> <li><a href="#implementing-support-for-other-cloud-services">Implementing Support for Other Cloud Services</a></li> <li><a href="#purging-unattached-uploads">Purging Unattached Uploads</a></li> </ol> </nav> </div> </header> <div class="wrapper"> <div id="column-main"> <section id="article-body"> <h2 id="what-is-active-storage-questionmark"><a class="anchorlink" href="#what-is-active-storage-questionmark" data-turbo="false">1 What is Active Storage?</a></h2>Active Storage facilitates uploading files to a cloud storage service like Amazon S3, Google Cloud Storage, or Microsoft Azure Storage and attaching those files to Active Record objects. It comes with a local disk-based service for development and testing and supports mirroring files to subordinate services for backups and migrations.Using Active Storage, an application can transform image uploads or generate image representations of non-image uploads like PDFs and videos, and extract metadata from arbitrary files.<h3 id="requirements"><a class="anchorlink" href="#requirements" data-turbo="false">1.1 Requirements</a></h3>Various features of Active Storage depend on third-party software which Rails will not install, and must be installed separately: <ul> <li><a href="https://github.com/libvips/libvips">libvips</a> v8.6+ or <a href="https://imagemagick.org/index.php">ImageMagick</a> for image analysis and transformations</li> <li><a href="http://ffmpeg.org/">ffmpeg</a> v3.4+ for video previews and ffprobe for video/audio analysis</li> <li><a href="https://poppler.freedesktop.org/">poppler</a> or <a href="https://mupdf.com/">muPDF</a> for PDF previews</li> </ul> Image analysis and transformations also require the <code>image_processing</code> gem. Uncomment it in your <code>Gemfile</code>, or add it if necessary:<div class="interstitial code"> <pre><code class="highlight ruby">gem "image_processing", ">= 1.2" </code></pre> <button class="clipboard-button" data-clipboard-text="gem "image_processing", ">= 1.2" ">Copy</button> </div> <div class="interstitial info">Compared to libvips, ImageMagick is better known and more widely available. However, libvips can be <a href="https://github.com/libvips/libvips/wiki/Speed-and-memory-use">up to 10x faster and consume 1/10 the memory</a>. For JPEG files, this can be further improved by replacing <code>libjpeg-dev</code> with <code>libjpeg-turbo-dev</code>, which is <a href="https://libjpeg-turbo.org/About/Performance">2-7x faster</a>.</div><div class="interstitial warning">Before you install and use third-party software, make sure you understand the licensing implications of doing so. MuPDF, in particular, is licensed under AGPL and requires a commercial license for some use.</div><h2 id="setup"><a class="anchorlink" href="#setup" data-turbo="false">2 Setup</a></h2><div class="interstitial code"> <pre><code class="highlight console">$ bin/rails active_storage:install $ bin/rails db:migrate </code></pre> <button class="clipboard-button" data-clipboard-text="bin/rails active_storage:install bin/rails db:migrate ">Copy</button> </div> This sets up configuration, and creates the three tables Active Storage uses: <code>active_storage_blobs</code>, <code>active_storage_attachments</code>, and <code>active_storage_variant_records</code>. <div class="table-wrapper"><table><thead> <tr> <th>Table</th> <th>Purpose</th> </tr> </thead><tbody> <tr> <td><code>active_storage_blobs</code></td> <td>Stores data about uploaded files, such as filename and content type.</td> </tr> <tr> <td><code>active_storage_attachments</code></td> <td>A polymorphic join table that <a href="#attaching-files-to-records">connects your models to blobs</a>. If your model's class name changes, you will need to run a migration on this table to update the underlying <code>record_type</code> to your model's new class name.</td> </tr> <tr> <td><code>active_storage_variant_records</code></td> <td>If <a href="#attaching-files-to-records">variant tracking</a> is enabled, stores records for each variant that has been generated.</td> </tr> </tbody></table></div> <div class="interstitial warning">If you are using UUIDs instead of integers as the primary key on your models, you should set <code>Rails.application.config.generators { |g| g.orm :active_record, primary_key_type: :uuid }</code> in a config file.</div>Declare Active Storage services in <code>config/storage.yml</code>. For each service your application uses, provide a name and the requisite configuration. The example below declares three services named <code>local</code>, <code>test</code>, and <code>amazon</code>:<div class="interstitial code"> <pre><code class="highlight yaml">local: service: Disk root: <%= Rails.root.join("storage") %> test: service: Disk root: <%= Rails.root.join("tmp/storage") %> # Use bin/rails credentials:edit to set the AWS secrets (as aws:access_key_id|secret_access_key) 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) %> bucket: your_own_bucket-<%= Rails.env %> region: "" # e.g. 'us-east-1' </code></pre> <button class="clipboard-button" data-clipboard-text="local: service: Disk root: <%= Rails.root.join("storage") %> test: service: Disk root: <%= Rails.root.join("tmp/storage") %> # Use bin/rails credentials:edit to set the AWS secrets (as aws:access_key_id|secret_access_key) 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) %> bucket: your_own_bucket-<%= Rails.env %> region: "" # e.g. 'us-east-1' ">Copy</button> </div> Tell Active Storage which service to use by setting <code>Rails.application.config.active_storage.service</code>. Because each environment will likely use a different service, it is recommended to do this on a per-environment basis. To use the disk service from the previous example in the development environment, you would add the following to <code>config/environments/development.rb</code>:<div class="interstitial code"> <pre><code class="highlight ruby"># Store files locally. config.active_storage.service = :local </code></pre> <button class="clipboard-button" data-clipboard-text="# Store files locally. config.active_storage.service = :local ">Copy</button> </div> To use the S3 service in production, you add the following to <code>config/environments/production.rb</code>:<div class="interstitial code"> <pre><code class="highlight ruby"># Store files on Amazon S3. config.active_storage.service = :amazon </code></pre> <button class="clipboard-button" data-clipboard-text="# Store files on Amazon S3. config.active_storage.service = :amazon ">Copy</button> </div> To use the test service when testing, you add the following to <code>config/environments/test.rb</code>:<div class="interstitial code"> <pre><code class="highlight ruby"># Store uploaded files on the local file system in a temporary directory. config.active_storage.service = :test </code></pre> <button class="clipboard-button" data-clipboard-text="# Store uploaded files on the local file system in a temporary directory. config.active_storage.service = :test ">Copy</button> </div> <div class="interstitial note">Configuration files that are environment-specific will take precedence: in production, for example, the <code>config/storage/production.yml</code> file (if existent) will take precedence over the <code>config/storage.yml</code> file.</div>It is recommended to use <code>Rails.env</code> in the bucket names to further reduce the risk of accidentally destroying production data.<div class="interstitial code"> <pre><code class="highlight yaml">amazon: service: S3 # ... bucket: your_own_bucket-<%= Rails.env %> google: service: GCS # ... bucket: your_own_bucket-<%= Rails.env %> azure: service: AzureStorage # ... container: your_container_name-<%= Rails.env %> </code></pre> <button class="clipboard-button" data-clipboard-text="amazon: service: S3 # ... bucket: your_own_bucket-<%= Rails.env %> google: service: GCS # ... bucket: your_own_bucket-<%= Rails.env %> azure: service: AzureStorage # ... container: your_container_name-<%= Rails.env %> ">Copy</button> </div> Continue reading for more information on the built-in service adapters (e.g. <code>Disk</code> and <code>S3</code>) and the configuration they require.<h3 id="disk-service"><a class="anchorlink" href="#disk-service" data-turbo="false">2.1 Disk Service</a></h3>Declare a Disk service in <code>config/storage.yml</code>:<div class="interstitial code"> <pre><code class="highlight yaml">local: service: Disk root: <%= Rails.root.join("storage") %> </code></pre> <button class="clipboard-button" data-clipboard-text="local: service: Disk root: <%= Rails.root.join("storage") %> ">Copy</button> </div> <h3 id="s3-service-amazon-s3-and-s3-compatible-apis"><a class="anchorlink" href="#s3-service-amazon-s3-and-s3-compatible-apis" data-turbo="false">2.2 S3 Service (Amazon S3 and S3-compatible APIs)</a></h3>To connect to Amazon S3, declare an S3 service in <code>config/storage.yml</code>:<div class="interstitial code"> <pre><code class="highlight yaml"># Use bin/rails credentials:edit to set the AWS secrets (as aws:access_key_id|secret_access_key) 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: "" # e.g. 'us-east-1' bucket: your_own_bucket-<%= Rails.env %> </code></pre> <button class="clipboard-button" data-clipboard-text="# Use bin/rails credentials:edit to set the AWS secrets (as aws:access_key_id|secret_access_key) 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: "" # e.g. 'us-east-1' bucket: your_own_bucket-<%= Rails.env %> ">Copy</button> </div> Optionally provide client and upload options:<div class="interstitial code"> <pre><code class="highlight yaml"># Use bin/rails credentials:edit to set the AWS secrets (as aws:access_key_id|secret_access_key) 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: "" # e.g. 'us-east-1' bucket: your_own_bucket-<%= Rails.env %> http_open_timeout: 0 http_read_timeout: 0 retry_limit: 0 upload: server_side_encryption: "" # 'aws:kms' or 'AES256' cache_control: "private, max-age=<%= 1.day.to_i %>" </code></pre> <button class="clipboard-button" data-clipboard-text="# Use bin/rails credentials:edit to set the AWS secrets (as aws:access_key_id|secret_access_key) 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: "" # e.g. 'us-east-1' bucket: your_own_bucket-<%= Rails.env %> http_open_timeout: 0 http_read_timeout: 0 retry_limit: 0 upload: server_side_encryption: "" # 'aws:kms' or 'AES256' cache_control: "private, max-age=<%= 1.day.to_i %>" ">Copy</button> </div> <div class="interstitial info">Set sensible client HTTP timeouts and retry limits for your application. In certain failure scenarios, the default AWS client configuration may cause connections to be held for up to several minutes and lead to request queuing.</div>Add the <a href="https://github.com/aws/aws-sdk-ruby"><code>aws-sdk-s3</code></a> gem to your <code>Gemfile</code>:<div class="interstitial code"> <pre><code class="highlight ruby">gem "aws-sdk-s3", require: false </code></pre> <button class="clipboard-button" data-clipboard-text="gem "aws-sdk-s3", require: false ">Copy</button> </div> <div class="interstitial note">The core features of Active Storage require the following permissions: <code>s3:ListBucket</code>, <code>s3:PutObject</code>, <code>s3:GetObject</code>, and <code>s3:DeleteObject</code>. <a href="#public-access">Public access</a> additionally requires <code>s3:PutObjectAcl</code>. If you have additional upload options configured such as setting ACLs then additional permissions may be required.</div><div class="interstitial note">If you want to use environment variables, standard SDK configuration files, profiles, IAM instance profiles or task roles, you can omit the <code>access_key_id</code>, <code>secret_access_key</code>, and <code>region</code> keys in the example above. The S3 Service supports all of the authentication options described in the <a href="https://docs.aws.amazon.com/sdk-for-ruby/v3/developer-guide/setup-config.html">AWS SDK documentation</a>.</div>To connect to an S3-compatible object storage API such as DigitalOcean Spaces, provide the <code>endpoint</code>:<div class="interstitial code"> <pre><code class="highlight yaml">digitalocean: service: S3 endpoint: https://nyc3.digitaloceanspaces.com access_key_id: <%= Rails.application.credentials.dig(:digitalocean, :access_key_id) %> secret_access_key: <%= Rails.application.credentials.dig(:digitalocean, :secret_access_key) %> # ...and other options </code></pre> <button class="clipboard-button" data-clipboard-text="digitalocean: service: S3 endpoint: https://nyc3.digitaloceanspaces.com access_key_id: <%= Rails.application.credentials.dig(:digitalocean, :access_key_id) %> secret_access_key: <%= Rails.application.credentials.dig(:digitalocean, :secret_access_key) %> # ...and other options ">Copy</button> </div> There are many other options available. You can check them in <a href="https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/S3/Client.html#initialize-instance_method">AWS S3 Client</a> documentation.<h3 id="microsoft-azure-storage-service"><a class="anchorlink" href="#microsoft-azure-storage-service" data-turbo="false">2.3 Microsoft Azure Storage Service</a></h3>Declare an Azure Storage service in <code>config/storage.yml</code>:<div class="interstitial code"> <pre><code class="highlight yaml"># Use bin/rails credentials:edit to set the Azure Storage secret (as azure_storage:storage_access_key) azure: service: AzureStorage storage_account_name: your_account_name storage_access_key: <%= Rails.application.credentials.dig(:azure_storage, :storage_access_key) %> container: your_container_name-<%= Rails.env %> </code></pre> <button class="clipboard-button" data-clipboard-text="# Use bin/rails credentials:edit to set the Azure Storage secret (as azure_storage:storage_access_key) azure: service: AzureStorage storage_account_name: your_account_name storage_access_key: <%= Rails.application.credentials.dig(:azure_storage, :storage_access_key) %> container: your_container_name-<%= Rails.env %> ">Copy</button> </div> Add the <a href="https://github.com/Azure/azure-storage-ruby"><code>azure-storage-blob</code></a> gem to your <code>Gemfile</code>:<div class="interstitial code"> <pre><code class="highlight ruby">gem "azure-storage-blob", "~> 2.0", require: false </code></pre> <button class="clipboard-button" data-clipboard-text="gem "azure-storage-blob", "~> 2.0", require: false ">Copy</button> </div> <h3 id="google-cloud-storage-service"><a class="anchorlink" href="#google-cloud-storage-service" data-turbo="false">2.4 Google Cloud Storage Service</a></h3>Declare a Google Cloud Storage service in <code>config/storage.yml</code>:<div class="interstitial code"> <pre><code class="highlight yaml">google: service: GCS credentials: <%= Rails.root.join("path/to/keyfile.json") %> project: "" bucket: your_own_bucket-<%= Rails.env %> </code></pre> <button class="clipboard-button" data-clipboard-text="google: service: GCS credentials: <%= Rails.root.join("path/to/keyfile.json") %> project: "" bucket: your_own_bucket-<%= Rails.env %> ">Copy</button> </div> Optionally provide a Hash of credentials instead of a keyfile path:<div class="interstitial code"> <pre><code class="highlight yaml"># Use bin/rails credentials:edit to set the GCS secrets (as gcs:private_key_id|private_key) google: service: GCS credentials: type: "service_account" project_id: "" private_key_id: <%= Rails.application.credentials.dig(:gcs, :private_key_id) %> private_key: <%= Rails.application.credentials.dig(:gcs, :private_key).dump %> client_email: "" client_id: "" auth_uri: "https://accounts.google.com/o/oauth2/auth" token_uri: "https://accounts.google.com/o/oauth2/token" auth_provider_x509_cert_url: "https://www.googleapis.com/oauth2/v1/certs" client_x509_cert_url: "" project: "" bucket: your_own_bucket-<%= Rails.env %> </code></pre> <button class="clipboard-button" data-clipboard-text="# Use bin/rails credentials:edit to set the GCS secrets (as gcs:private_key_id|private_key) google: service: GCS credentials: type: "service_account" project_id: "" private_key_id: <%= Rails.application.credentials.dig(:gcs, :private_key_id) %> private_key: <%= Rails.application.credentials.dig(:gcs, :private_key).dump %> client_email: "" client_id: "" auth_uri: "https://accounts.google.com/o/oauth2/auth" token_uri: "https://accounts.google.com/o/oauth2/token" auth_provider_x509_cert_url: "https://www.googleapis.com/oauth2/v1/certs" client_x509_cert_url: "" project: "" bucket: your_own_bucket-<%= Rails.env %> ">Copy</button> </div> Optionally provide a Cache-Control metadata to set on uploaded assets:<div class="interstitial code"> <pre><code class="highlight yaml">google: service: GCS ... cache_control: "public, max-age=3600" </code></pre> <button class="clipboard-button" data-clipboard-text="google: service: GCS ... cache_control: "public, max-age=3600" ">Copy</button> </div> Optionally use <a href="https://cloud.google.com/storage/docs/access-control/signed-urls#signing-iam">IAM</a> instead of the <code>credentials</code> when signing URLs. This is useful if you are authenticating your GKE applications with Workload Identity, see <a href="https://cloud.google.com/blog/products/containers-kubernetes/introducing-workload-identity-better-authentication-for-your-gke-applications">this Google Cloud blog post</a> for more information.<div class="interstitial code"> <pre><code class="highlight yaml">google: service: GCS ... iam: true </code></pre> <button class="clipboard-button" data-clipboard-text="google: service: GCS ... iam: true ">Copy</button> </div> Optionally use a specific GSA when signing URLs. When using IAM, the <a href="https://cloud.google.com/compute/docs/storing-retrieving-metadata">metadata server</a> will be contacted to get the GSA email, but this metadata server is not always present (e.g. local tests) and you may wish to use a non-default GSA.<div class="interstitial code"> <pre><code class="highlight yaml">google: service: GCS ... iam: true gsa_email: "foobar@baz.iam.gserviceaccount.com" </code></pre> <button class="clipboard-button" data-clipboard-text="google: service: GCS ... iam: true gsa_email: "foobar@baz.iam.gserviceaccount.com" ">Copy</button> </div> Add the <a href="https://github.com/GoogleCloudPlatform/google-cloud-ruby/tree/main/google-cloud-storage"><code>google-cloud-storage</code></a> gem to your <code>Gemfile</code>:<div class="interstitial code"> <pre><code class="highlight ruby">gem "google-cloud-storage", "~> 1.11", require: false </code></pre> <button class="clipboard-button" data-clipboard-text="gem "google-cloud-storage", "~> 1.11", require: false ">Copy</button> </div> <h3 id="mirror-service"><a class="anchorlink" href="#mirror-service" data-turbo="false">2.5 Mirror Service</a></h3>You can keep multiple services in sync by defining a mirror service. A mirror service replicates uploads and deletes across two or more subordinate services.A mirror service is intended to be used temporarily during a migration between services in production. You can start mirroring to a new service, copy pre-existing files from the old service to the new, then go all-in on the new service.<div class="interstitial note">Mirroring is not atomic. It is possible for an upload to succeed on the primary service and fail on any of the subordinate services. Before going all-in on a new service, verify that all files have been copied.</div>Define each of the services you'd like to mirror as described above. Reference them by name when defining a mirror service:<div class="interstitial code"> <pre><code class="highlight yaml"># Use bin/rails credentials:edit to set the AWS secrets (as aws:access_key_id|secret_access_key) s3_west_coast: 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: "" # e.g. 'us-west-1' bucket: your_own_bucket-<%= Rails.env %> s3_east_coast: 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: "" # e.g. 'us-east-1' bucket: your_own_bucket-<%= Rails.env %> production: service: Mirror primary: s3_east_coast mirrors: - s3_west_coast </code></pre> <button class="clipboard-button" data-clipboard-text="# Use bin/rails credentials:edit to set the AWS secrets (as aws:access_key_id|secret_access_key) s3_west_coast: 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: "" # e.g. 'us-west-1' bucket: your_own_bucket-<%= Rails.env %> s3_east_coast: 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: "" # e.g. 'us-east-1' bucket: your_own_bucket-<%= Rails.env %> production: service: Mirror primary: s3_east_coast mirrors: - s3_west_coast ">Copy</button> </div> Although all secondary services receive uploads, downloads are always handled by the primary service.Mirror services are compatible with direct uploads. New files are directly uploaded to the primary service. When a directly-uploaded file is attached to a record, a background job is enqueued to copy it to the secondary services.<h3 id="public-access"><a class="anchorlink" href="#public-access" data-turbo="false">2.6 Public access</a></h3>By default, Active Storage assumes private access to services. This means generating signed, single-use URLs for blobs. If you'd rather make blobs publicly accessible, specify <code>public: true</code> in your app's <code>config/storage.yml</code>:<div class="interstitial code"> <pre><code class="highlight yaml">gcs: &gcs service: GCS project: "" private_gcs: <<: *gcs credentials: <%= Rails.root.join("path/to/private_key.json") %> bucket: your_own_bucket-<%= Rails.env %> public_gcs: <<: *gcs credentials: <%= Rails.root.join("path/to/public_key.json") %> bucket: your_own_bucket-<%= Rails.env %> public: true </code></pre> <button class="clipboard-button" data-clipboard-text="gcs: &gcs service: GCS project: "" private_gcs: <<: *gcs credentials: <%= Rails.root.join("path/to/private_key.json") %> bucket: your_own_bucket-<%= Rails.env %> public_gcs: <<: *gcs credentials: <%= Rails.root.join("path/to/public_key.json") %> bucket: your_own_bucket-<%= Rails.env %> public: true ">Copy</button> </div> Make sure your buckets are properly configured for public access. See docs on how to enable public read permissions for <a href="https://docs.aws.amazon.com/AmazonS3/latest/user-guide/block-public-access-bucket.html">Amazon S3</a>, <a href="https://cloud.google.com/storage/docs/access-control/making-data-public#buckets">Google Cloud Storage</a>, and <a href="https://docs.microsoft.com/en-us/azure/storage/blobs/storage-manage-access-to-resources#set-container-public-access-level-in-the-azure-portal">Microsoft Azure</a> storage services. Amazon S3 additionally requires that you have the <code>s3:PutObjectAcl</code> permission.When converting an existing application to use <code>public: true</code>, make sure to update every individual file in the bucket to be publicly-readable before switching over.<h2 id="attaching-files-to-records"><a class="anchorlink" href="#attaching-files-to-records" data-turbo="false">3 Attaching Files to Records</a></h2><h3 id="has-one-attached"><a class="anchorlink" href="#has-one-attached" data-turbo="false">3.1 <code>has_one_attached</code></a></h3>The <a href="https://api.rubyonrails.org/v8.0.0/classes/ActiveStorage/Attached/Model.html#method-i-has_one_attached"><code>has_one_attached</code></a> macro sets up a one-to-one mapping between records and files. Each record can have one file attached to it.For example, suppose your application has a <code>User</code> model. If you want each user to have an avatar, define the <code>User</code> model as follows:<div class="interstitial code"> <pre><code class="highlight ruby">class User < ApplicationRecord has_one_attached :avatar end </code></pre> <button class="clipboard-button" data-clipboard-text="class User < ApplicationRecord has_one_attached :avatar end ">Copy</button> </div> or if you are using Rails 6.0+, you can run a model generator command like this:<div class="interstitial code"> <pre><code class="highlight console">$ bin/rails generate model User avatar:attachment </code></pre> <button class="clipboard-button" data-clipboard-text="bin/rails generate model User avatar:attachment ">Copy</button> </div> You can create a user with an avatar:<div class="interstitial code"> <pre><code class="highlight erb"><%= form.file_field :avatar %> </code></pre> <button class="clipboard-button" data-clipboard-text="<%= form.file_field :avatar %> ">Copy</button> </div> <div class="interstitial code"> <pre><code class="highlight ruby">class SignupController < ApplicationController def create user = User.create!(user_params) session[:user_id] = user.id redirect_to root_path end private def user_params params.expect(user: [:email_address, :password, :avatar]) end end </code></pre> <button class="clipboard-button" data-clipboard-text="class SignupController < ApplicationController def create user = User.create!(user_params) session[:user_id] = user.id redirect_to root_path end private def user_params params.expect(user: [:email_address, :password, :avatar]) end end ">Copy</button> </div> Call <a href="https://api.rubyonrails.org/v8.0.0/classes/ActiveStorage/Attached/One.html#method-i-attach"><code>avatar.attach</code></a> to attach an avatar to an existing user:<div class="interstitial code"> <pre><code class="highlight ruby">user.avatar.attach(params[:avatar]) </code></pre> <button class="clipboard-button" data-clipboard-text="user.avatar.attach(params[:avatar]) ">Copy</button> </div> Call <a href="https://api.rubyonrails.org/v8.0.0/classes/ActiveStorage/Attached/One.html#method-i-attached-3F"><code>avatar.attached?</code></a> to determine whether a particular user has an avatar:<div class="interstitial code"> <pre><code class="highlight ruby">user.avatar.attached? </code></pre> <button class="clipboard-button" data-clipboard-text="user.avatar.attached? ">Copy</button> </div> In some cases you might want to override a default service for a specific attachment. You can configure specific services per attachment using the <code>service</code> option with the name of your service:<div class="interstitial code"> <pre><code class="highlight ruby">class User < ApplicationRecord has_one_attached :avatar, service: :google end </code></pre> <button class="clipboard-button" data-clipboard-text="class User < ApplicationRecord has_one_attached :avatar, service: :google end ">Copy</button> </div> You can configure specific variants per attachment by calling the <code>variant</code> method on yielded attachable object:<div class="interstitial code"> <pre><code class="highlight ruby">class User < ApplicationRecord has_one_attached :avatar do |attachable| attachable.variant :thumb, resize_to_limit: [100, 100] end end </code></pre> <button class="clipboard-button" data-clipboard-text="class User < ApplicationRecord has_one_attached :avatar do |attachable| attachable.variant :thumb, resize_to_limit: [100, 100] end end ">Copy</button> </div> Call <code>avatar.variant(:thumb)</code> to get a thumb variant of an avatar:<div class="interstitial code"> <pre><code class="highlight erb"><%= image_tag user.avatar.variant(:thumb) %> </code></pre> <button class="clipboard-button" data-clipboard-text="<%= image_tag user.avatar.variant(:thumb) %> ">Copy</button> </div> You can use specific variants for previews as well:<div class="interstitial code"> <pre><code class="highlight ruby">class User < ApplicationRecord has_one_attached :video do |attachable| attachable.variant :thumb, resize_to_limit: [100, 100] end end </code></pre> <button class="clipboard-button" data-clipboard-text="class User < ApplicationRecord has_one_attached :video do |attachable| attachable.variant :thumb, resize_to_limit: [100, 100] end end ">Copy</button> </div> <div class="interstitial code"> <pre><code class="highlight erb"><%= image_tag user.video.preview(:thumb) %> </code></pre> <button class="clipboard-button" data-clipboard-text="<%= image_tag user.video.preview(:thumb) %> ">Copy</button> </div> If you know in advance that your variants will be accessed, you can specify that Rails should generate them ahead of time:<div class="interstitial code"> <pre><code class="highlight ruby">class User < ApplicationRecord has_one_attached :video do |attachable| attachable.variant :thumb, resize_to_limit: [100, 100], preprocessed: true end end </code></pre> <button class="clipboard-button" data-clipboard-text="class User < ApplicationRecord has_one_attached :video do |attachable| attachable.variant :thumb, resize_to_limit: [100, 100], preprocessed: true end end ">Copy</button> </div> Rails will enqueue a job to generate the variant after the attachment is attached to the record.<div class="interstitial note">Since Active Storage relies on polymorphic associations, and <a href="./association_basics.html#polymorphic-associations">polymorphic associations</a> rely on storing class names in the database, that data must remain synchronized with the class name used by the Ruby code. When renaming classes that use <code>has_one_attached</code>, make sure to also update the class names in the <code>active_storage_attachments.record_type</code> polymorphic type column of the corresponding rows.</div><h3 id="has-many-attached"><a class="anchorlink" href="#has-many-attached" data-turbo="false">3.2 <code>has_many_attached</code></a></h3>The <a href="https://api.rubyonrails.org/v8.0.0/classes/ActiveStorage/Attached/Model.html#method-i-has_many_attached"><code>has_many_attached</code></a> macro sets up a one-to-many relationship between records and files. Each record can have many files attached to it.For example, suppose your application has a <code>Message</code> model. If you want each message to have many images, define the <code>Message</code> model as follows:<div class="interstitial code"> <pre><code class="highlight ruby">class Message < ApplicationRecord has_many_attached :images end </code></pre> <button class="clipboard-button" data-clipboard-text="class Message < ApplicationRecord has_many_attached :images end ">Copy</button> </div> or if you are using Rails 6.0+, you can run a model generator command like this:<div class="interstitial code"> <pre><code class="highlight console">$ bin/rails generate model Message images:attachments </code></pre> <button class="clipboard-button" data-clipboard-text="bin/rails generate model Message images:attachments ">Copy</button> </div> You can create a message with images:<div class="interstitial code"> <pre><code class="highlight ruby">class MessagesController < ApplicationController def create message = Message.create!(message_params) redirect_to message end private def message_params params.expect(message: [ :title, :content, images: [] ]) end end </code></pre> <button class="clipboard-button" data-clipboard-text="class MessagesController < ApplicationController def create message = Message.create!(message_params) redirect_to message end private def message_params params.expect(message: [ :title, :content, images: [] ]) end end ">Copy</button> </div> Call <a href="https://api.rubyonrails.org/v8.0.0/classes/ActiveStorage/Attached/Many.html#method-i-attach"><code>images.attach</code></a> to add new images to an existing message:<div class="interstitial code"> <pre><code class="highlight ruby">@message.images.attach(params[:images]) </code></pre> <button class="clipboard-button" data-clipboard-text="@message.images.attach(params[:images]) ">Copy</button> </div> Call <a href="https://api.rubyonrails.org/v8.0.0/classes/ActiveStorage/Attached/Many.html#method-i-attached-3F"><code>images.attached?</code></a> to determine whether a particular message has any images:<div class="interstitial code"> <pre><code class="highlight ruby">@message.images.attached? </code></pre> <button class="clipboard-button" data-clipboard-text="@message.images.attached? ">Copy</button> </div> Overriding the default service is done the same way as <code>has_one_attached</code>, by using the <code>service</code> option:<div class="interstitial code"> <pre><code class="highlight ruby">class Message < ApplicationRecord has_many_attached :images, service: :s3 end </code></pre> <button class="clipboard-button" data-clipboard-text="class Message < ApplicationRecord has_many_attached :images, service: :s3 end ">Copy</button> </div> Configuring specific variants is done the same way as <code>has_one_attached</code>, by calling the <code>variant</code> method on the yielded attachable object:<div class="interstitial code"> <pre><code class="highlight ruby">class Message < ApplicationRecord has_many_attached :images do |attachable| attachable.variant :thumb, resize_to_limit: [100, 100] end end </code></pre> <button class="clipboard-button" data-clipboard-text="class Message < ApplicationRecord has_many_attached :images do |attachable| attachable.variant :thumb, resize_to_limit: [100, 100] end end ">Copy</button> </div> <div class="interstitial note">Since Active Storage relies on polymorphic associations, and <a href="./association_basics.html#polymorphic-associations">polymorphic associations</a> rely on storing class names in the database, that data must remain synchronized with the class name used by the Ruby code. When renaming classes that use <code>has_many_attached</code>, make sure to also update the class names in the <code>active_storage_attachments.record_type</code> polymorphic type column of the corresponding rows.</div><h3 id="attaching-file-io-objects"><a class="anchorlink" href="#attaching-file-io-objects" data-turbo="false">3.3 Attaching File/IO Objects</a></h3>Sometimes you need to attach a file that doesn’t arrive via an HTTP request. For example, you may want to attach a file you generated on disk or downloaded from a user-submitted URL. You may also want to attach a fixture file in a model test. To do that, provide a Hash containing at least an open IO object and a filename:<div class="interstitial code"> <pre><code class="highlight ruby">@message.images.attach(io: File.open("/path/to/file"), filename: "file.pdf") </code></pre> <button class="clipboard-button" data-clipboard-text="@message.images.attach(io: File.open("/path/to/file"), filename: "file.pdf") ">Copy</button> </div> When possible, provide a content type as well. Active Storage attempts to determine a file’s content type from its data. It falls back to the content type you provide if it can’t do that.<div class="interstitial code"> <pre><code class="highlight ruby">@message.images.attach(io: File.open("/path/to/file"), filename: "file.pdf", content_type: "application/pdf") </code></pre> <button class="clipboard-button" data-clipboard-text="@message.images.attach(io: File.open("/path/to/file"), filename: "file.pdf", content_type: "application/pdf") ">Copy</button> </div> You can bypass the content type inference from the data by passing in <code>identify: false</code> along with the <code>content_type</code>.<div class="interstitial code"> <pre><code class="highlight ruby">@message.images.attach( io: File.open("/path/to/file"), filename: "file.pdf", content_type: "application/pdf", identify: false ) </code></pre> <button class="clipboard-button" data-clipboard-text="@message.images.attach( io: File.open("/path/to/file"), filename: "file.pdf", content_type: "application/pdf", identify: false ) ">Copy</button> </div> If you don’t provide a content type and Active Storage can’t determine the file’s content type automatically, it defaults to application/octet-stream.There is an additional parameter <code>key</code> that can be used to specify folders/sub-folders in your S3 Bucket. AWS S3 otherwise uses a random key to name your files. This approach is helpful if you want to organize your S3 Bucket files better.<div class="interstitial code"> <pre><code class="highlight ruby">@message.images.attach( io: File.open("/path/to/file"), filename: "file.pdf", content_type: "application/pdf", key: "#{Rails.env}/blog_content/intuitive_filename.pdf", identify: false ) </code></pre> <button class="clipboard-button" data-clipboard-text="@message.images.attach( io: File.open("/path/to/file"), filename: "file.pdf", content_type: "application/pdf", key: "#{Rails.env}/blog_content/intuitive_filename.pdf", identify: false ) ">Copy</button> </div> This way the file will get saved in the folder <code>[S3_BUCKET]/development/blog_content/</code> when you test this from your development environment. Note that if you use the key parameter, you have to ensure the key to be unique for the upload to go through. It is recommended to append the filename with a unique random key, something like:<div class="interstitial code"> <pre><code class="highlight ruby">def s3_file_key "#{Rails.env}/blog_content/intuitive_filename-#{SecureRandom.uuid}.pdf" end </code></pre> <button class="clipboard-button" data-clipboard-text="def s3_file_key "#{Rails.env}/blog_content/intuitive_filename-#{SecureRandom.uuid}.pdf" end ">Copy</button> </div> <div class="interstitial code"> <pre><code class="highlight ruby">@message.images.attach( io: File.open("/path/to/file"), filename: "file.pdf", content_type: "application/pdf", key: s3_file_key, identify: false ) </code></pre> <button class="clipboard-button" data-clipboard-text="@message.images.attach( io: File.open("/path/to/file"), filename: "file.pdf", content_type: "application/pdf", key: s3_file_key, identify: false ) ">Copy</button> </div> <h3 id="replacing-vs-adding-attachments"><a class="anchorlink" href="#replacing-vs-adding-attachments" data-turbo="false">3.4 Replacing vs Adding Attachments</a></h3>By default in Rails, attaching files to a <code>has_many_attached</code> association will replace any existing attachments.To keep existing attachments, you can use hidden form fields with the <a href="https://api.rubyonrails.org/v8.0.0/classes/ActiveStorage/Blob.html#method-i-signed_id"><code>signed_id</code></a> of each attached file:<div class="interstitial code"> <pre><code class="highlight erb"><% @message.images.each do |image| %> <%= form.hidden_field :images, multiple: true, value: image.signed_id %> <% end %> <%= form.file_field :images, multiple: true %> </code></pre> <button class="clipboard-button" data-clipboard-text="<% @message.images.each do |image| %> <%= form.hidden_field :images, multiple: true, value: image.signed_id %> <% end %> <%= form.file_field :images, multiple: true %> ">Copy</button> </div> This has the advantage of making it possible to remove existing attachments selectively, e.g. by using JavaScript to remove individual hidden fields.<h3 id="form-validation"><a class="anchorlink" href="#form-validation" data-turbo="false">3.5 Form Validation</a></h3>Attachments aren't sent to the storage service until a successful <code>save</code> on the associated record. This means that if a form submission fails validation, any new attachment(s) will be lost and must be uploaded again. Since <a href="#direct-uploads">direct uploads</a> are stored before the form is submitted, they can be used to retain uploads when validation fails:<div class="interstitial code"> <pre><code class="highlight erb"><%= form.hidden_field :avatar, value: @user.avatar.signed_id if @user.avatar.attached? %> <%= form.file_field :avatar, direct_upload: true %> </code></pre> <button class="clipboard-button" data-clipboard-text="<%= form.hidden_field :avatar, value: @user.avatar.signed_id if @user.avatar.attached? %> <%= form.file_field :avatar, direct_upload: true %> ">Copy</button> </div> <h2 id="removing-files"><a class="anchorlink" href="#removing-files" data-turbo="false">4 Removing Files</a></h2>To remove an attachment from a model, call <a href="https://api.rubyonrails.org/v8.0.0/classes/ActiveStorage/Attached/One.html#method-i-purge"><code>purge</code></a> on the attachment. If your application is set up to use Active Job, removal can be done in the background instead by calling <a href="https://api.rubyonrails.org/v8.0.0/classes/ActiveStorage/Attached/One.html#method-i-purge_later"><code>purge_later</code></a>. Purging deletes the blob and the file from the storage service.<div class="interstitial code"> <pre><code class="highlight ruby"># Synchronously destroy the avatar and actual resource files. user.avatar.purge # Destroy the associated models and actual resource files async, via Active Job. user.avatar.purge_later </code></pre> <button class="clipboard-button" data-clipboard-text="# Synchronously destroy the avatar and actual resource files. user.avatar.purge # Destroy the associated models and actual resource files async, via Active Job. user.avatar.purge_later ">Copy</button> </div> <h2 id="serving-files"><a class="anchorlink" href="#serving-files" data-turbo="false">5 Serving Files</a></h2>Active Storage supports two ways to serve files: redirecting and proxying.<div class="interstitial warning">All Active Storage controllers are publicly accessible by default. The generated URLs are hard to guess, but permanent by design. If your files require a higher level of protection consider implementing <a href="#authenticated-controllers">Authenticated Controllers</a>.</div><h3 id="redirect-mode"><a class="anchorlink" href="#redirect-mode" data-turbo="false">5.1 Redirect Mode</a></h3>To generate a permanent URL for a blob, you can pass the blob to the <a href="https://api.rubyonrails.org/v8.0.0/classes/ActionView/RoutingUrlFor.html#method-i-url_for"><code>url_for</code></a> view helper. This generates a URL with the blob's <a href="https://api.rubyonrails.org/v8.0.0/classes/ActiveStorage/Blob.html#method-i-signed_id"><code>signed_id</code></a> that is routed to the blob's <a href="https://api.rubyonrails.org/v8.0.0/classes/ActiveStorage/Blobs/RedirectController.html"><code>RedirectController</code></a><div class="interstitial code"> <pre><code class="highlight ruby">url_for(user.avatar) # => https://www.example.com/rails/active_storage/blobs/redirect/:signed_id/my-avatar.png </code></pre> <button class="clipboard-button" data-clipboard-text="url_for(user.avatar) # => https://www.example.com/rails/active_storage/blobs/redirect/:signed_id/my-avatar.png ">Copy</button> </div> The <code>RedirectController</code> redirects to the actual service endpoint. This indirection decouples the service URL from the actual one, and allows, for example, mirroring attachments in different services for high-availability. The redirection has an HTTP expiration of 5 minutes.To create a download link, use the <code>rails_blob_{path|url}</code> helper. Using this helper allows you to set the disposition.<div class="interstitial code"> <pre><code class="highlight ruby">rails_blob_path(user.avatar, disposition: "attachment") </code></pre> <button class="clipboard-button" data-clipboard-text="rails_blob_path(user.avatar, disposition: "attachment") ">Copy</button> </div> <div class="interstitial warning">To prevent XSS attacks, Active Storage forces the Content-Disposition header to "attachment" for some kind of files. To change this behavior see the available configuration options in <a href="configuring.html#configuring-active-storage">Configuring Rails Applications</a>.</div>If you need to create a link from outside of controller/view context (Background jobs, Cronjobs, etc.), you can access the <code>rails_blob_path</code> like this:<div class="interstitial code"> <pre><code class="highlight ruby">Rails.application.routes.url_helpers.rails_blob_path(user.avatar, only_path: true) </code></pre> <button class="clipboard-button" data-clipboard-text="Rails.application.routes.url_helpers.rails_blob_path(user.avatar, only_path: true) ">Copy</button> </div> <h3 id="proxy-mode"><a class="anchorlink" href="#proxy-mode" data-turbo="false">5.2 Proxy Mode</a></h3>Optionally, files can be proxied instead. This means that your application servers will download file data from the storage service in response to requests. This can be useful for serving files from a CDN.You can configure Active Storage to use proxying by default:<div class="interstitial code"> <pre><code class="highlight ruby"># config/initializers/active_storage.rb Rails.application.config.active_storage.resolve_model_to_route = :rails_storage_proxy </code></pre> <button class="clipboard-button" data-clipboard-text="Rails.application.config.active_storage.resolve_model_to_route = :rails_storage_proxy ">Copy</button> </div> Or if you want to explicitly proxy specific attachments there are URL helpers you can use in the form of <code>rails_storage_proxy_path</code> and <code>rails_storage_proxy_url</code>.<div class="interstitial code"> <pre><code class="highlight erb"><%= image_tag rails_storage_proxy_path(@user.avatar) %> </code></pre> <button class="clipboard-button" data-clipboard-text="<%= image_tag rails_storage_proxy_path(@user.avatar) %> ">Copy</button> </div> <h4 id="putting-a-cdn-in-front-of-active-storage"><a class="anchorlink" href="#putting-a-cdn-in-front-of-active-storage" data-turbo="false">5.2.1 Putting a CDN in Front of Active Storage</a></h4>Additionally, in order to use a CDN for Active Storage attachments, you will need to generate URLs with proxy mode so that they are served by your app and the CDN will cache the attachment without any extra configuration. This works out of the box because the default Active Storage proxy controller sets an HTTP header indicating to the CDN to cache the response.You should also make sure that the generated URLs use the CDN host instead of your app host. There are multiple ways to achieve this, but in general it involves tweaking your <code>config/routes.rb</code> file so that you can generate the proper URLs for the attachments and their variations. As an example, you could add this:<div class="interstitial code"> <pre><code class="highlight ruby"># config/routes.rb direct :cdn_image do |model, options| expires_in = options.delete(:expires_in) { ActiveStorage.urls_expire_in } if model.respond_to?(:signed_id) route_for( :rails_service_blob_proxy, model.signed_id(expires_in: expires_in), model.filename, options.merge(host: ENV["CDN_HOST"]) ) else signed_blob_id = model.blob.signed_id(expires_in: expires_in) variation_key = model.variation.key filename = model.blob.filename route_for( :rails_blob_representation_proxy, signed_blob_id, variation_key, filename, options.merge(host: ENV["CDN_HOST"]) ) end end </code></pre> <button class="clipboard-button" data-clipboard-text="direct :cdn_image do |model, options| expires_in = options.delete(:expires_in) { ActiveStorage.urls_expire_in } if model.respond_to?(:signed_id) route_for( :rails_service_blob_proxy, model.signed_id(expires_in: expires_in), model.filename, options.merge(host: ENV["CDN_HOST"]) ) else signed_blob_id = model.blob.signed_id(expires_in: expires_in) variation_key = model.variation.key filename = model.blob.filename route_for( :rails_blob_representation_proxy, signed_blob_id, variation_key, filename, options.merge(host: ENV["CDN_HOST"]) ) end end ">Copy</button> </div> and then generate routes like this:<div class="interstitial code"> <pre><code class="highlight erb"><%= cdn_image_url(user.avatar.variant(resize_to_limit: [128, 128])) %> </code></pre> <button class="clipboard-button" data-clipboard-text="<%= cdn_image_url(user.avatar.variant(resize_to_limit: [128, 128])) %> ">Copy</button> </div> <h3 id="authenticated-controllers"><a class="anchorlink" href="#authenticated-controllers" data-turbo="false">5.3 Authenticated Controllers</a></h3>All Active Storage controllers are publicly accessible by default. The generated URLs use a plain <a href="https://api.rubyonrails.org/v8.0.0/classes/ActiveStorage/Blob.html#method-i-signed_id"><code>signed_id</code></a>, making them hard to guess but permanent. Anyone that knows the blob URL will be able to access it, even if a <code>before_action</code> in your <code>ApplicationController</code> would otherwise require a login. If your files require a higher level of protection, you can implement your own authenticated controllers, based on the <a href="https://api.rubyonrails.org/v8.0.0/classes/ActiveStorage/Blobs/RedirectController.html"><code>ActiveStorage::Blobs::RedirectController</code></a>, <a href="https://api.rubyonrails.org/v8.0.0/classes/ActiveStorage/Blobs/ProxyController.html"><code>ActiveStorage::Blobs::ProxyController</code></a>, <a href="https://api.rubyonrails.org/v8.0.0/classes/ActiveStorage/Representations/RedirectController.html"><code>ActiveStorage::Representations::RedirectController</code></a> and <a href="https://api.rubyonrails.org/v8.0.0/classes/ActiveStorage/Representations/ProxyController.html"><code>ActiveStorage::Representations::ProxyController</code></a>To only allow an account to access their own logo you could do the following:<div class="interstitial code"> <pre><code class="highlight ruby"># config/routes.rb resource :account do resource :logo end </code></pre> <button class="clipboard-button" data-clipboard-text="resource :account do resource :logo end ">Copy</button> </div> <div class="interstitial code"> <pre><code class="highlight ruby"># app/controllers/logos_controller.rb class LogosController < ApplicationController # Through ApplicationController: # include Authenticate, SetCurrentAccount def show redirect_to Current.account.logo.url end end </code></pre> <button class="clipboard-button" data-clipboard-text="class LogosController < ApplicationController # Through ApplicationController: # include Authenticate, SetCurrentAccount def show redirect_to Current.account.logo.url end end ">Copy</button> </div> <div class="interstitial code"> <pre><code class="highlight erb"><%= image_tag account_logo_path %> </code></pre> <button class="clipboard-button" data-clipboard-text="<%= image_tag account_logo_path %> ">Copy</button> </div> And then you should disable the Active Storage default routes with:<div class="interstitial code"> <pre><code class="highlight ruby">config.active_storage.draw_routes = false </code></pre> <button class="clipboard-button" data-clipboard-text="config.active_storage.draw_routes = false ">Copy</button> </div> to prevent files being accessed with the publicly accessible URLs.<h2 id="downloading-files"><a class="anchorlink" href="#downloading-files" data-turbo="false">6 Downloading Files</a></h2>Sometimes you need to process a blob after it’s uploaded—for example, to convert it to a different format. Use the attachment's <a href="https://api.rubyonrails.org/v8.0.0/classes/ActiveStorage/Blob.html#method-i-download"><code>download</code></a> method to read a blob’s binary data into memory:<div class="interstitial code"> <pre><code class="highlight ruby">binary = user.avatar.download </code></pre> <button class="clipboard-button" data-clipboard-text="binary = user.avatar.download ">Copy</button> </div> You might want to download a blob to a file on disk so an external program (e.g. a virus scanner or media transcoder) can operate on it. Use the attachment's <a href="https://api.rubyonrails.org/v8.0.0/classes/ActiveStorage/Blob.html#method-i-open"><code>open</code></a> method to download a blob to a tempfile on disk:<div class="interstitial code"> <pre><code class="highlight ruby">message.video.open do |file| system "/path/to/virus/scanner", file.path # ... end </code></pre> <button class="clipboard-button" data-clipboard-text="message.video.open do |file| system "/path/to/virus/scanner", file.path # ... end ">Copy</button> </div> It's important to know that the file is not yet available in the <code>after_create</code> callback but in the <code>after_create_commit</code> only.<h2 id="analyzing-files"><a class="anchorlink" href="#analyzing-files" data-turbo="false">7 Analyzing Files</a></h2>Active Storage analyzes files once they've been uploaded by queuing a job in Active Job. Analyzed files will store additional information in the metadata hash, including <code>analyzed: true</code>. You can check whether a blob has been analyzed by calling <a href="https://api.rubyonrails.org/v8.0.0/classes/ActiveStorage/Blob/Analyzable.html#method-i-analyzed-3F"><code>analyzed?</code></a> on it.Image analysis provides <code>width</code> and <code>height</code> attributes. Video analysis provides these, as well as <code>duration</code>, <code>angle</code>, <code>display_aspect_ratio</code>, and <code>video</code> and <code>audio</code> booleans to indicate the presence of those channels. Audio analysis provides <code>duration</code> and <code>bit_rate</code> attributes.<h2 id="displaying-images-videos-and-pdfs"><a class="anchorlink" href="#displaying-images-videos-and-pdfs" data-turbo="false">8 Displaying Images, Videos, and PDFs</a></h2>Active Storage supports representing a variety of files. You can call <a href="https://api.rubyonrails.org/v8.0.0/classes/ActiveStorage/Blob/Representable.html#method-i-representation"><code>representation</code></a> on an attachment to display an image variant, or a preview of a video or PDF. Before calling <code>representation</code>, check if the attachment can be represented by calling <a href="https://api.rubyonrails.org/v8.0.0/classes/ActiveStorage/Blob/Representable.html#method-i-representable-3F"><code>representable?</code></a>. Some file formats can't be previewed by Active Storage out of the box (e.g. Word documents); if <code>representable?</code> returns false you may want to <a href="#serving-files">link to</a> the file instead.<div class="interstitial code"> <pre><code class="highlight erb"><ul> <% @message.files.each do |file| %> <li> <% if file.representable? %> <%= image_tag file.representation(resize_to_limit: [100, 100]) %> <% else %> <%= link_to rails_blob_path(file, disposition: "attachment") do %> <%= image_tag "placeholder.png", alt: "Download file" %> <% end %> <% end %> </li> <% end %> </ul> </code></pre> <button class="clipboard-button" data-clipboard-text="<ul> <% @message.files.each do |file| %> <li> <% if file.representable? %> <%= image_tag file.representation(resize_to_limit: [100, 100]) %> <% else %> <%= link_to rails_blob_path(file, disposition: "attachment") do %> <%= image_tag "placeholder.png", alt: "Download file" %> <% end %> <% end %> </li> <% end %> </ul> ">Copy</button> </div> Internally, <code>representation</code> calls <code>variant</code> for images, and <code>preview</code> for previewable files. You can also call these methods directly.<h3 id="lazy-vs-immediate-loading"><a class="anchorlink" href="#lazy-vs-immediate-loading" data-turbo="false">8.1 Lazy vs Immediate Loading</a></h3>By default, Active Storage will process representations lazily. This code:<div class="interstitial code"> <pre><code class="highlight ruby">image_tag file.representation(resize_to_limit: [100, 100]) </code></pre> <button class="clipboard-button" data-clipboard-text="image_tag file.representation(resize_to_limit: [100, 100]) ">Copy</button> </div> Will generate an <code><img></code> tag with the <code>src</code> pointing to the <a href="https://api.rubyonrails.org/v8.0.0/classes/ActiveStorage/Representations/RedirectController.html"><code>ActiveStorage::Representations::RedirectController</code></a>. The browser will make a request to that controller, which will perform the following: <ol> <li>Process file and upload the processed file if necessary.</li> <li>Return a <code>302</code> redirect to the file either to <ul> <li>the remote service (e.g., S3).</li> <li>or <code>ActiveStorage::Blobs::ProxyController</code> which will return the file contents if <a href="#proxy-mode">proxy mode</a> is enabled.</li> </ul></li> </ol> Loading the file lazily allows features like <a href="#public-access">single use URLs</a> to work without slowing down your initial page loads.This works fine for most cases.If you want to generate URLs for images immediately, you can call <code>.processed.url</code>:<div class="interstitial code"> <pre><code class="highlight ruby">image_tag file.representation(resize_to_limit: [100, 100]).processed.url </code></pre> <button class="clipboard-button" data-clipboard-text="image_tag file.representation(resize_to_limit: [100, 100]).processed.url ">Copy</button> </div> The Active Storage variant tracker improves performance of this, by storing a record in the database if the requested representation has been processed before. Thus, the above code will only make an API call to the remote service (e.g. S3) once, and once a variant is stored, will use that. The variant tracker runs automatically, but can be disabled through <a href="configuring.html#config-active-storage-track-variants"><code>config.active_storage.track_variants</code></a>.If you're rendering lots of images on a page, the above example could result in N+1 queries loading all the variant records. To avoid these N+1 queries, use the named scopes on <a href="https://api.rubyonrails.org/v8.0.0/classes/ActiveStorage/Attachment.html"><code>ActiveStorage::Attachment</code></a>.<div class="interstitial code"> <pre><code class="highlight ruby">message.images.with_all_variant_records.each do |file| image_tag file.representation(resize_to_limit: [100, 100]).processed.url end </code></pre> <button class="clipboard-button" data-clipboard-text="message.images.with_all_variant_records.each do |file| image_tag file.representation(resize_to_limit: [100, 100]).processed.url end ">Copy</button> </div> <h3 id="transforming-images"><a class="anchorlink" href="#transforming-images" data-turbo="false">8.2 Transforming Images</a></h3>Transforming images allows you to display the image at your choice of dimensions. To create a variation of an image, call <a href="https://api.rubyonrails.org/v8.0.0/classes/ActiveStorage/Blob/Representable.html#method-i-variant"><code>variant</code></a> on the attachment. You can pass any transformation supported by the variant processor to the method. When the browser hits the variant URL, Active Storage will lazily transform the original blob into the specified format and redirect to its new service location.<div class="interstitial code"> <pre><code class="highlight erb"><%= image_tag user.avatar.variant(resize_to_limit: [100, 100]) %> </code></pre> <button class="clipboard-button" data-clipboard-text="<%= image_tag user.avatar.variant(resize_to_limit: [100, 100]) %> ">Copy</button> </div> If a variant is requested, Active Storage will automatically apply transformations depending on the image's format: <ol> <li>Content types that are variable (as dictated by <a href="configuring.html#config-active-storage-variable-content-types"><code>config.active_storage.variable_content_types</code></a>) and not considered web images (as dictated by <a href="configuring.html#config-active-storage-web-image-content-types"><code>config.active_storage.web_image_content_types</code></a>), will be converted to PNG.</li> <li>If <code>quality</code> is not specified, the variant processor's default quality for the format will be used.</li> </ol> Active Storage can use either <a href="https://www.rubydoc.info/gems/ruby-vips/Vips/Image">Vips</a> or MiniMagick as the variant processor. The default depends on your <code>config.load_defaults</code> target version, and the processor can be changed by setting <a href="configuring.html#config-active-storage-variant-processor"><code>config.active_storage.variant_processor</code></a>.The parameters available are defined by the <a href="https://github.com/janko/image_processing"><code>image_processing</code></a> gem and depend on the variant processor that you are using, but both support the following parameters: <div class="table-wrapper"><table><thead> <tr> <th>Parameter</th> <th>Example</th> <th>Description</th> </tr> </thead><tbody> <tr> <td><code>resize_to_limit</code></td> <td><code>resize_to_limit: [100, 100]</code></td> <td>Downsizes the image to fit within the specified dimensions while retaining the original aspect ratio. Will only resize the image if it's larger than the specified dimensions.</td> </tr> <tr> <td><code>resize_to_fit</code></td> <td><code>resize_to_fit: [100, 100]</code></td> <td>Resizes the image to fit within the specified dimensions while retaining the original aspect ratio. Will downsize the image if it's larger than the specified dimensions or upsize if it's smaller.</td> </tr> <tr> <td><code>resize_to_fill</code></td> <td><code>resize_to_fill: [100, 100]</code></td> <td>Resizes the image to fill the specified dimensions while retaining the original aspect ratio. If necessary, will crop the image in the larger dimension.</td> </tr> <tr> <td><code>resize_and_pad</code></td> <td><code>resize_and_pad: [100, 100]</code></td> <td>Resizes the image to fit within the specified dimensions while retaining the original aspect ratio. If necessary, will pad the remaining area with transparent color if source image has alpha channel, black otherwise.</td> </tr> <tr> <td><code>crop</code></td> <td><code>crop: [20, 50, 300, 300]</code></td> <td>Extracts an area from an image. The first two arguments are the left and top edges of area to extract, while the last two arguments are the width and height of the area to extract.</td> </tr> <tr> <td><code>rotate</code></td> <td><code>rotate: 90</code></td> <td>Rotates the image by the specified angle.</td> </tr> </tbody></table></div> <a href="https://github.com/janko/image_processing"><code>image_processing</code></a> has all parameters available in it's own documentation for both the <a href="https://github.com/janko/image_processing/blob/master/doc/vips.md">Vips</a> and <a href="https://github.com/janko/image_processing/blob/master/doc/minimagick.md">MiniMagick</a> processors.Some parameters, including those listed above, accept additional processor specific options which can be passed as <code>key: value</code> pairs inside a hash:<div class="interstitial code"> <pre><code class="highlight erb"> <%= image_tag user.avatar.variant(resize_to_fill: [100, 100, { crop: :centre }]) %> </code></pre> <button class="clipboard-button" data-clipboard-text=" <%= image_tag user.avatar.variant(resize_to_fill: [100, 100, { crop: :centre }]) %> ">Copy</button> </div> If migrating an existing application between MiniMagick and Vips, processor specific options will need to be updated:<div class="interstitial code"> <pre><code class="highlight erb"> <%= image_tag user.avatar.variant(resize_to_limit: [100, 100], format: :jpeg, sampling_factor: "4:2:0", strip: true, interlace: "JPEG", colorspace: "sRGB", quality: 80) %>  <%= image_tag user.avatar.variant(resize_to_limit: [100, 100], format: :jpeg, saver: { subsample_mode: "on", strip: true, interlace: true, quality: 80 }) %> </code></pre> <button class="clipboard-button" data-clipboard-text=" <%= image_tag user.avatar.variant(resize_to_limit: [100, 100], format: :jpeg, sampling_factor: "4:2:0", strip: true, interlace: "JPEG", colorspace: "sRGB", quality: 80) %>  <%= image_tag user.avatar.variant(resize_to_limit: [100, 100], format: :jpeg, saver: { subsample_mode: "on", strip: true, interlace: true, quality: 80 }) %> ">Copy</button> </div> <h3 id="previewing-files"><a class="anchorlink" href="#previewing-files" data-turbo="false">8.3 Previewing Files</a></h3>Some non-image files can be previewed: that is, they can be presented as images. For example, a video file can be previewed by extracting its first frame. Out of the box, Active Storage supports previewing videos and PDF documents. To create a link to a lazily-generated preview, use the attachment's <a href="https://api.rubyonrails.org/v8.0.0/classes/ActiveStorage/Blob/Representable.html#method-i-preview"><code>preview</code></a> method:<div class="interstitial code"> <pre><code class="highlight erb"><%= image_tag message.video.preview(resize_to_limit: [100, 100]) %> </code></pre> <button class="clipboard-button" data-clipboard-text="<%= image_tag message.video.preview(resize_to_limit: [100, 100]) %> ">Copy</button> </div> To add support for another format, add your own previewer. See the <a href="https://api.rubyonrails.org/v8.0.0/classes/ActiveStorage/Preview.html"><code>ActiveStorage::Preview</code></a> documentation for more information.<h2 id="direct-uploads"><a class="anchorlink" href="#direct-uploads" data-turbo="false">9 Direct Uploads</a></h2>Active Storage, with its included JavaScript library, supports uploading directly from the client to the cloud.<h3 id="usage"><a class="anchorlink" href="#usage" data-turbo="false">9.1 Usage</a></h3> <ol> <li>Include <code>activestorage.js</code> in your application's JavaScript bundle.Using the asset pipeline:<div class="interstitial code"> <pre><code class="highlight js">//= require activestorage </code></pre> <button class="clipboard-button" data-clipboard-text="//= require activestorage ">Copy</button> </div> Using the npm package:<div class="interstitial code"> <pre><code class="highlight js">import * as ActiveStorage from "@rails/activestorage" ActiveStorage.start() </code></pre> <button class="clipboard-button" data-clipboard-text="import * as ActiveStorage from "@rails/activestorage" ActiveStorage.start() ">Copy</button> </div></li> <li>Add <code>direct_upload: true</code> to your <a href="form_helpers.html#uploading-files">file field</a>:<div class="interstitial code"> <pre><code class="highlight erb"><%= form.file_field :attachments, multiple: true, direct_upload: true %> </code></pre> <button class="clipboard-button" data-clipboard-text="<%= form.file_field :attachments, multiple: true, direct_upload: true %> ">Copy</button> </div> Or, if you aren't using a <code>FormBuilder</code>, add the data attribute directly:<div class="interstitial code"> <pre><code class="highlight erb"><input type="file" data-direct-upload-url="<%= rails_direct_uploads_url %>" /> </code></pre> <button class="clipboard-button" data-clipboard-text="<input type="file" data-direct-upload-url="<%= rails_direct_uploads_url %>" /> ">Copy</button> </div></li> <li>Configure CORS on third-party storage services to allow direct upload requests.</li> <li>That's it! Uploads begin upon form submission.</li> </ol> <h3 id="cross-origin-resource-sharing-cors-configuration"><a class="anchorlink" href="#cross-origin-resource-sharing-cors-configuration" data-turbo="false">9.2 Cross-Origin Resource Sharing (CORS) Configuration</a></h3>To make direct uploads to a third-party service work, you’ll need to configure the service to allow cross-origin requests from your app. Consult the CORS documentation for your service: <ul> <li><a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/enabling-cors-examples.html">S3</a></li> <li><a href="https://cloud.google.com/storage/docs/configuring-cors">Google Cloud Storage</a></li> <li><a href="https://docs.microsoft.com/en-us/rest/api/storageservices/cross-origin-resource-sharing--cors--support-for-the-azure-storage-services">Azure Storage</a></li> </ul> Take care to allow: <ul> <li>All origins from which your app is accessed</li> <li>The <code>PUT</code> request method</li> <li>The following headers: <ul> <li><code>Content-Type</code></li> <li><code>Content-MD5</code></li> <li><code>Content-Disposition</code> (except for Azure Storage)</li> <li><code>x-ms-blob-content-disposition</code> (for Azure Storage only)</li> <li><code>x-ms-blob-type</code> (for Azure Storage only)</li> <li><code>Cache-Control</code> (for GCS, only if <code>cache_control</code> is set)</li> </ul></li> </ul> No CORS configuration is required for the Disk service since it shares your app’s origin.<h4 id="example-s3-cors-configuration"><a class="anchorlink" href="#example-s3-cors-configuration" data-turbo="false">9.2.1 Example: S3 CORS Configuration</a></h4><div class="interstitial code"> <pre><code class="highlight json">[ { "AllowedHeaders": [ "Content-Type", "Content-MD5", "Content-Disposition" ], "AllowedMethods": [ "PUT" ], "AllowedOrigins": [ "https://www.example.com" ], "MaxAgeSeconds": 3600 } ] </code></pre> <button class="clipboard-button" data-clipboard-text="[ { "AllowedHeaders": [ "Content-Type", "Content-MD5", "Content-Disposition" ], "AllowedMethods": [ "PUT" ], "AllowedOrigins": [ "https://www.example.com" ], "MaxAgeSeconds": 3600 } ] ">Copy</button> </div> <h4 id="example-google-cloud-storage-cors-configuration"><a class="anchorlink" href="#example-google-cloud-storage-cors-configuration" data-turbo="false">9.2.2 Example: Google Cloud Storage CORS Configuration</a></h4><div class="interstitial code"> <pre><code class="highlight json">[ { "origin": ["https://www.example.com"], "method": ["PUT"], "responseHeader": ["Content-Type", "Content-MD5", "Content-Disposition"], "maxAgeSeconds": 3600 } ] </code></pre> <button class="clipboard-button" data-clipboard-text="[ { "origin": ["https://www.example.com"], "method": ["PUT"], "responseHeader": ["Content-Type", "Content-MD5", "Content-Disposition"], "maxAgeSeconds": 3600 } ] ">Copy</button> </div> <h4 id="example-azure-storage-cors-configuration"><a class="anchorlink" href="#example-azure-storage-cors-configuration" data-turbo="false">9.2.3 Example: Azure Storage CORS Configuration</a></h4><div class="interstitial code"> <pre><code class="highlight xml"><Cors> <CorsRule> <AllowedOrigins>https://www.example.com</AllowedOrigins> <AllowedMethods>PUT</AllowedMethods> <AllowedHeaders>Content-Type, Content-MD5, x-ms-blob-content-disposition, x-ms-blob-type</AllowedHeaders> <MaxAgeInSeconds>3600</MaxAgeInSeconds> </CorsRule> </Cors> </code></pre> <button class="clipboard-button" data-clipboard-text="<Cors> <CorsRule> <AllowedOrigins>https://www.example.com</AllowedOrigins> <AllowedMethods>PUT</AllowedMethods> <AllowedHeaders>Content-Type, Content-MD5, x-ms-blob-content-disposition, x-ms-blob-type</AllowedHeaders> <MaxAgeInSeconds>3600</MaxAgeInSeconds> </CorsRule> </Cors> ">Copy</button> </div> <h3 id="direct-upload-javascript-events"><a class="anchorlink" href="#direct-upload-javascript-events" data-turbo="false">9.3 Direct Upload JavaScript Events</a></h3> <div class="table-wrapper"><table><thead> <tr> <th>Event name</th> <th>Event target</th> <th>Event data (<code>event.detail</code>)</th> <th>Description</th> </tr> </thead><tbody> <tr> <td><code>direct-uploads:start</code></td> <td><code><form></code></td> <td>None</td> <td>A form containing files for direct upload fields was submitted.</td> </tr> <tr> <td><code>direct-upload:initialize</code></td> <td><code><input></code></td> <td><code>{id, file}</code></td> <td>Dispatched for every file after form submission.</td> </tr> <tr> <td><code>direct-upload:start</code></td> <td><code><input></code></td> <td><code>{id, file}</code></td> <td>A direct upload is starting.</td> </tr> <tr> <td><code>direct-upload:before-blob-request</code></td> <td><code><input></code></td> <td><code>{id, file, xhr}</code></td> <td>Before making a request to your application for direct upload metadata.</td> </tr> <tr> <td><code>direct-upload:before-storage-request</code></td> <td><code><input></code></td> <td><code>{id, file, xhr}</code></td> <td>Before making a request to store a file.</td> </tr> <tr> <td><code>direct-upload:progress</code></td> <td><code><input></code></td> <td><code>{id, file, progress}</code></td> <td>As requests to store files progress.</td> </tr> <tr> <td><code>direct-upload:error</code></td> <td><code><input></code></td> <td><code>{id, file, error}</code></td> <td>An error occurred. An <code>alert</code> will display unless this event is canceled.</td> </tr> <tr> <td><code>direct-upload:end</code></td> <td><code><input></code></td> <td><code>{id, file}</code></td> <td>A direct upload has ended.</td> </tr> <tr> <td><code>direct-uploads:end</code></td> <td><code><form></code></td> <td>None</td> <td>All direct uploads have ended.</td> </tr> </tbody></table></div> <h3 id="example"><a class="anchorlink" href="#example" data-turbo="false">9.4 Example</a></h3>You can use these events to show the progress of an upload.<img src="https://user-images.githubusercontent.com/5355/28694528-16e69d0c-72f8-11e7-91a7-c0b8cfc90391.gif" alt="direct-uploads">To show the uploaded files in a form:<div class="interstitial code"> <pre><code class="highlight js">// direct_uploads.js addEventListener("direct-upload:initialize", event => { const { target, detail } = event const { id, file } = detail target.insertAdjacentHTML("beforebegin", ` <div id="direct-upload-${id}" class="direct-upload direct-upload--pending"> <div id="direct-upload-progress-${id}" class="direct-upload__progress" style="width: 0%"></div> </div> `) target.previousElementSibling.querySelector(`.direct-upload__filename`).textContent = file.name }) addEventListener("direct-upload:start", event => { const { id } = event.detail const element = document.getElementById(`direct-upload-${id}`) element.classList.remove("direct-upload--pending") }) addEventListener("direct-upload:progress", event => { const { id, progress } = event.detail const progressElement = document.getElementById(`direct-upload-progress-${id}`) progressElement.style.width = `${progress}%` }) addEventListener("direct-upload:error", event => { event.preventDefault() const { id, error } = event.detail const element = document.getElementById(`direct-upload-${id}`) element.classList.add("direct-upload--error") element.setAttribute("title", error) }) addEventListener("direct-upload:end", event => { const { id } = event.detail const element = document.getElementById(`direct-upload-${id}`) element.classList.add("direct-upload--complete") }) </code></pre> <button class="clipboard-button" data-clipboard-text="// direct_uploads.js addEventListener("direct-upload:initialize", event => { const { target, detail } = event const { id, file } = detail target.insertAdjacentHTML("beforebegin", ` <div id="direct-upload-${id}" class="direct-upload direct-upload--pending"> <div id="direct-upload-progress-${id}" class="direct-upload__progress" style="width: 0%"></div> </div> `) target.previousElementSibling.querySelector(`.direct-upload__filename`).textContent = file.name }) addEventListener("direct-upload:start", event => { const { id } = event.detail const element = document.getElementById(`direct-upload-${id}`) element.classList.remove("direct-upload--pending") }) addEventListener("direct-upload:progress", event => { const { id, progress } = event.detail const progressElement = document.getElementById(`direct-upload-progress-${id}`) progressElement.style.width = `${progress}%` }) addEventListener("direct-upload:error", event => { event.preventDefault() const { id, error } = event.detail const element = document.getElementById(`direct-upload-${id}`) element.classList.add("direct-upload--error") element.setAttribute("title", error) }) addEventListener("direct-upload:end", event => { const { id } = event.detail const element = document.getElementById(`direct-upload-${id}`) element.classList.add("direct-upload--complete") }) ">Copy</button> </div> Add styles:<div class="interstitial code"> <pre><code class="highlight css">/* direct_uploads.css */ .direct-upload { display: inline-block; position: relative; padding: 2px 4px; margin: 0 3px 3px 0; border: 1px solid rgba(0, 0, 0, 0.3); border-radius: 3px; font-size: 11px; line-height: 13px; } .direct-upload--pending { opacity: 0.6; } .direct-upload__progress { position: absolute; top: 0; left: 0; bottom: 0; opacity: 0.2; background: #0076ff; transition: width 120ms ease-out, opacity 60ms 60ms ease-in; transform: translate3d(0, 0, 0); } .direct-upload--complete .direct-upload__progress { opacity: 0.4; } .direct-upload--error { border-color: red; } input[type=file][data-direct-upload-url][disabled] { display: none; } </code></pre> <button class="clipboard-button" data-clipboard-text="/* direct_uploads.css */ .direct-upload { display: inline-block; position: relative; padding: 2px 4px; margin: 0 3px 3px 0; border: 1px solid rgba(0, 0, 0, 0.3); border-radius: 3px; font-size: 11px; line-height: 13px; } .direct-upload--pending { opacity: 0.6; } .direct-upload__progress { position: absolute; top: 0; left: 0; bottom: 0; opacity: 0.2; background: #0076ff; transition: width 120ms ease-out, opacity 60ms 60ms ease-in; transform: translate3d(0, 0, 0); } .direct-upload--complete .direct-upload__progress { opacity: 0.4; } .direct-upload--error { border-color: red; } input[type=file][data-direct-upload-url][disabled] { display: none; } ">Copy</button> </div> <h3 id="custom-drag-and-drop-solutions"><a class="anchorlink" href="#custom-drag-and-drop-solutions" data-turbo="false">9.5 Custom drag and drop solutions</a></h3>You can use the <code>DirectUpload</code> class for this purpose. Upon receiving a file from your library of choice, instantiate a DirectUpload and call its create method. Create takes a callback to invoke when the upload completes.<div class="interstitial code"> <pre><code class="highlight js">import { DirectUpload } from "@rails/activestorage" const input = document.querySelector('input[type=file]') // Bind to file drop - use the ondrop on a parent element or use a // library like Dropzone const onDrop = (event) => { event.preventDefault() const files = event.dataTransfer.files; Array.from(files).forEach(file => uploadFile(file)) } // Bind to normal file selection input.addEventListener('change', (event) => { Array.from(input.files).forEach(file => uploadFile(file)) // you might clear the selected files from the input input.value = null }) const uploadFile = (file) => { // your form needs the file_field direct_upload: true, which // provides data-direct-upload-url const url = input.dataset.directUploadUrl const upload = new DirectUpload(file, url) upload.create((error, blob) => { if (error) { // Handle the error } else { // Add an appropriately-named hidden input to the form with a // value of blob.signed_id so that the blob ids will be // transmitted in the normal upload flow const hiddenField = document.createElement('input') hiddenField.setAttribute("type", "hidden"); hiddenField.setAttribute("value", blob.signed_id); hiddenField.name = input.name document.querySelector('form').appendChild(hiddenField) } }) } </code></pre> <button class="clipboard-button" data-clipboard-text="import { DirectUpload } from "@rails/activestorage" const input = document.querySelector('input[type=file]') // Bind to file drop - use the ondrop on a parent element or use a // library like Dropzone const onDrop = (event) => { event.preventDefault() const files = event.dataTransfer.files; Array.from(files).forEach(file => uploadFile(file)) } // Bind to normal file selection input.addEventListener('change', (event) => { Array.from(input.files).forEach(file => uploadFile(file)) // you might clear the selected files from the input input.value = null }) const uploadFile = (file) => { // your form needs the file_field direct_upload: true, which // provides data-direct-upload-url const url = input.dataset.directUploadUrl const upload = new DirectUpload(file, url) upload.create((error, blob) => { if (error) { // Handle the error } else { // Add an appropriately-named hidden input to the form with a // value of blob.signed_id so that the blob ids will be // transmitted in the normal upload flow const hiddenField = document.createElement('input') hiddenField.setAttribute("type", "hidden"); hiddenField.setAttribute("value", blob.signed_id); hiddenField.name = input.name document.querySelector('form').appendChild(hiddenField) } }) } ">Copy</button> </div> <h3 id="track-the-progress-of-the-file-upload"><a class="anchorlink" href="#track-the-progress-of-the-file-upload" data-turbo="false">9.6 Track the progress of the file upload</a></h3>When using the <code>DirectUpload</code> constructor, it is possible to include a third parameter. This will allow the <code>DirectUpload</code> object to invoke the <code>directUploadWillStoreFileWithXHR</code> method during the upload process. You can then attach your own progress handler to the XHR to suit your needs.<div class="interstitial code"> <pre><code class="highlight js">import { DirectUpload } from "@rails/activestorage" class Uploader { constructor(file, url) { this.upload = new DirectUpload(file, url, this) } uploadFile(file) { this.upload.create((error, blob) => { if (error) { // Handle the error } else { // Add an appropriately-named hidden input to the form // with a value of blob.signed_id } }) } directUploadWillStoreFileWithXHR(request) { request.upload.addEventListener("progress", event => this.directUploadDidProgress(event)) } directUploadDidProgress(event) { // Use event.loaded and event.total to update the progress bar } } </code></pre> <button class="clipboard-button" data-clipboard-text="import { DirectUpload } from "@rails/activestorage" class Uploader { constructor(file, url) { this.upload = new DirectUpload(file, url, this) } uploadFile(file) { this.upload.create((error, blob) => { if (error) { // Handle the error } else { // Add an appropriately-named hidden input to the form // with a value of blob.signed_id } }) } directUploadWillStoreFileWithXHR(request) { request.upload.addEventListener("progress", event => this.directUploadDidProgress(event)) } directUploadDidProgress(event) { // Use event.loaded and event.total to update the progress bar } } ">Copy</button> </div> <h3 id="integrating-with-libraries-or-frameworks"><a class="anchorlink" href="#integrating-with-libraries-or-frameworks" data-turbo="false">9.7 Integrating with Libraries or Frameworks</a></h3>Once you receive a file from the library you have selected, you need to create a <code>DirectUpload</code> instance and use its "create" method to initiate the upload process, adding any required additional headers as necessary. The "create" method also requires a callback function to be provided that will be triggered once the upload has finished.<div class="interstitial code"> <pre><code class="highlight js">import { DirectUpload } from "@rails/activestorage" class Uploader { constructor(file, url, token) { const headers = { 'Authentication': `Bearer ${token}` } // INFO: Sending headers is an optional parameter. If you choose not to send headers, // authentication will be performed using cookies or session data. this.upload = new DirectUpload(file, url, this, headers) } uploadFile(file) { this.upload.create((error, blob) => { if (error) { // Handle the error } else { // Use the with blob.signed_id as a file reference in next request } }) } directUploadWillStoreFileWithXHR(request) { request.upload.addEventListener("progress", event => this.directUploadDidProgress(event)) } directUploadDidProgress(event) { // Use event.loaded and event.total to update the progress bar } } </code></pre> <button class="clipboard-button" data-clipboard-text="import { DirectUpload } from "@rails/activestorage" class Uploader { constructor(file, url, token) { const headers = { 'Authentication': `Bearer ${token}` } // INFO: Sending headers is an optional parameter. If you choose not to send headers, // authentication will be performed using cookies or session data. this.upload = new DirectUpload(file, url, this, headers) } uploadFile(file) { this.upload.create((error, blob) => { if (error) { // Handle the error } else { // Use the with blob.signed_id as a file reference in next request } }) } directUploadWillStoreFileWithXHR(request) { request.upload.addEventListener("progress", event => this.directUploadDidProgress(event)) } directUploadDidProgress(event) { // Use event.loaded and event.total to update the progress bar } } ">Copy</button> </div> To implement customized authentication, a new controller must be created on the Rails application, similar to the following:<div class="interstitial code"> <pre><code class="highlight ruby">class DirectUploadsController < ActiveStorage::DirectUploadsController skip_forgery_protection before_action :authenticate! def authenticate! @token = request.headers["Authorization"]&.split&.last head :unauthorized unless valid_token?(@token) end end </code></pre> <button class="clipboard-button" data-clipboard-text="class DirectUploadsController < ActiveStorage::DirectUploadsController skip_forgery_protection before_action :authenticate! def authenticate! @token = request.headers["Authorization"]&.split&.last head :unauthorized unless valid_token?(@token) end end ">Copy</button> </div> <div class="interstitial note">Using <a href="#direct-uploads">Direct Uploads</a> can sometimes result in a file that uploads, but never attaches to a record. Consider <a href="#purging-unattached-uploads">purging unattached uploads</a>.</div><h2 id="testing"><a class="anchorlink" href="#testing" data-turbo="false">10 Testing</a></h2>Use <a href="https://api.rubyonrails.org/v8.0.0/classes/ActionDispatch/TestProcess/FixtureFile.html#method-i-file_fixture_upload"><code>file_fixture_upload</code></a> to test uploading a file in an integration or controller test. Rails handles files like any other parameter.<div class="interstitial code"> <pre><code class="highlight ruby">class SignupController < ActionDispatch::IntegrationTest test "can sign up" do post signup_path, params: { name: "David", avatar: file_fixture_upload("david.png", "image/png") } user = User.order(:created_at).last assert user.avatar.attached? end end </code></pre> <button class="clipboard-button" data-clipboard-text="class SignupController < ActionDispatch::IntegrationTest test "can sign up" do post signup_path, params: { name: "David", avatar: file_fixture_upload("david.png", "image/png") } user = User.order(:created_at).last assert user.avatar.attached? end end ">Copy</button> </div> <h3 id="discarding-files-created-during-tests"><a class="anchorlink" href="#discarding-files-created-during-tests" data-turbo="false">10.1 Discarding Files Created During Tests</a></h3><h4 id="system-tests"><a class="anchorlink" href="#system-tests" data-turbo="false">10.1.1 System Tests</a></h4>System tests clean up test data by rolling back a transaction. Because <code>destroy</code> is never called on an object, the attached files are never cleaned up. If you want to clear the files, you can do it in an <code>after_teardown</code> callback. Doing it here ensures that all connections created during the test are complete and you won't receive an error from Active Storage saying it can't find a file.<div class="interstitial code"> <pre><code class="highlight ruby">class ApplicationSystemTestCase < ActionDispatch::SystemTestCase # ... def after_teardown super FileUtils.rm_rf(ActiveStorage::Blob.service.root) end # ... end </code></pre> <button class="clipboard-button" data-clipboard-text="class ApplicationSystemTestCase < ActionDispatch::SystemTestCase # ... def after_teardown super FileUtils.rm_rf(ActiveStorage::Blob.service.root) end # ... end ">Copy</button> </div> If you're using <a href="testing.html#parallel-testing">parallel tests</a> and the <code>DiskService</code>, you should configure each process to use its own folder for Active Storage. This way, the <code>teardown</code> callback will only delete files from the relevant process' tests.<div class="interstitial code"> <pre><code class="highlight ruby">class ApplicationSystemTestCase < ActionDispatch::SystemTestCase # ... parallelize_setup do |i| ActiveStorage::Blob.service.root = "#{ActiveStorage::Blob.service.root}-#{i}" end # ... end </code></pre> <button class="clipboard-button" data-clipboard-text="class ApplicationSystemTestCase < ActionDispatch::SystemTestCase # ... parallelize_setup do |i| ActiveStorage::Blob.service.root = "#{ActiveStorage::Blob.service.root}-#{i}" end # ... end ">Copy</button> </div> If your system tests verify the deletion of a model with attachments and you're using Active Job, set your test environment to use the inline queue adapter so the purge job is executed immediately rather at an unknown time in the future.<div class="interstitial code"> <pre><code class="highlight ruby"># Use inline job processing to make things happen immediately config.active_job.queue_adapter = :inline </code></pre> <button class="clipboard-button" data-clipboard-text="# Use inline job processing to make things happen immediately config.active_job.queue_adapter = :inline ">Copy</button> </div> <h4 id="integration-tests"><a class="anchorlink" href="#integration-tests" data-turbo="false">10.1.2 Integration Tests</a></h4>Similarly to System Tests, files uploaded during Integration Tests will not be automatically cleaned up. If you want to clear the files, you can do it in an <code>teardown</code> callback.<div class="interstitial code"> <pre><code class="highlight ruby">class ActionDispatch::IntegrationTest def after_teardown super FileUtils.rm_rf(ActiveStorage::Blob.service.root) end end </code></pre> <button class="clipboard-button" data-clipboard-text="class ActionDispatch::IntegrationTest def after_teardown super FileUtils.rm_rf(ActiveStorage::Blob.service.root) end end ">Copy</button> </div> If you're using <a href="testing.html#parallel-testing">parallel tests</a> and the Disk service, you should configure each process to use its own folder for Active Storage. This way, the <code>teardown</code> callback will only delete files from the relevant process' tests.<div class="interstitial code"> <pre><code class="highlight ruby">class ActionDispatch::IntegrationTest parallelize_setup do |i| ActiveStorage::Blob.service.root = "#{ActiveStorage::Blob.service.root}-#{i}" end end </code></pre> <button class="clipboard-button" data-clipboard-text="class ActionDispatch::IntegrationTest parallelize_setup do |i| ActiveStorage::Blob.service.root = "#{ActiveStorage::Blob.service.root}-#{i}" end end ">Copy</button> </div> <h3 id="adding-attachments-to-fixtures"><a class="anchorlink" href="#adding-attachments-to-fixtures" data-turbo="false">10.2 Adding Attachments to Fixtures</a></h3>You can add attachments to your existing <a href="testing.html#the-low-down-on-fixtures">fixtures</a>. First, you'll want to create a separate storage service:<div class="interstitial code"> <pre><code class="highlight yml"># config/storage.yml test_fixtures: service: Disk root: <%= Rails.root.join("tmp/storage_fixtures") %> </code></pre> <button class="clipboard-button" data-clipboard-text=" test_fixtures: service: Disk root: <%= Rails.root.join("tmp/storage_fixtures") %> ">Copy</button> </div> This tells Active Storage where to "upload" fixture files to, so it should be a temporary directory. By making it a different directory to your regular <code>test</code> service, you can separate fixture files from files uploaded during a test.Next, create fixture files for the Active Storage classes:<div class="interstitial code"> <pre><code class="highlight yml"># active_storage/attachments.yml david_avatar: name: avatar record: david (User) blob: david_avatar_blob </code></pre> <button class="clipboard-button" data-clipboard-text="# active_storage/attachments.yml david_avatar: name: avatar record: david (User) blob: david_avatar_blob ">Copy</button> </div> <div class="interstitial code"> <pre><code class="highlight yml"># active_storage/blobs.yml david_avatar_blob: <%= ActiveStorage::FixtureSet.blob filename: "david.png", service_name: "test_fixtures" %> </code></pre> <button class="clipboard-button" data-clipboard-text="# active_storage/blobs.yml david_avatar_blob: <%= ActiveStorage::FixtureSet.blob filename: "david.png", service_name: "test_fixtures" %> ">Copy</button> </div> Then put a file in your fixtures directory (the default path is <code>test/fixtures/files</code>) with the corresponding filename. See the <a href="https://api.rubyonrails.org/v8.0.0/classes/ActiveStorage/FixtureSet.html"><code>ActiveStorage::FixtureSet</code></a> docs for more information.Once everything is set up, you'll be able to access attachments in your tests:<div class="interstitial code"> <pre><code class="highlight ruby">class UserTest < ActiveSupport::TestCase def test_avatar avatar = users(:david).avatar assert avatar.attached? assert_not_nil avatar.download assert_equal 1000, avatar.byte_size end end </code></pre> <button class="clipboard-button" data-clipboard-text="class UserTest < ActiveSupport::TestCase def test_avatar avatar = users(:david).avatar assert avatar.attached? assert_not_nil avatar.download assert_equal 1000, avatar.byte_size end end ">Copy</button> </div> <h4 id="cleaning-up-fixtures"><a class="anchorlink" href="#cleaning-up-fixtures" data-turbo="false">10.2.1 Cleaning up Fixtures</a></h4>While files uploaded in tests are cleaned up <a href="#discarding-files-created-during-tests">at the end of each test</a>, you only need to clean up fixture files once: when all your tests complete.If you're using parallel tests, call <code>parallelize_teardown</code>:<div class="interstitial code"> <pre><code class="highlight ruby">class ActiveSupport::TestCase # ... parallelize_teardown do |i| FileUtils.rm_rf(ActiveStorage::Blob.services.fetch(:test_fixtures).root) end # ... end </code></pre> <button class="clipboard-button" data-clipboard-text="class ActiveSupport::TestCase # ... parallelize_teardown do |i| FileUtils.rm_rf(ActiveStorage::Blob.services.fetch(:test_fixtures).root) end # ... end ">Copy</button> </div> If you're not running parallel tests, use <code>Minitest.after_run</code> or the equivalent for your test framework (e.g. <code>after(:suite)</code> for RSpec):<div class="interstitial code"> <pre><code class="highlight ruby"># test_helper.rb Minitest.after_run do FileUtils.rm_rf(ActiveStorage::Blob.services.fetch(:test_fixtures).root) end </code></pre> <button class="clipboard-button" data-clipboard-text="# test_helper.rb Minitest.after_run do FileUtils.rm_rf(ActiveStorage::Blob.services.fetch(:test_fixtures).root) end ">Copy</button> </div> <h3 id="configuring-services"><a class="anchorlink" href="#configuring-services" data-turbo="false">10.3 Configuring services</a></h3>You can add <code>config/storage/test.yml</code> to configure services to be used in test environment. This is useful when the <code>service</code> option is used.<div class="interstitial code"> <pre><code class="highlight ruby">class User < ApplicationRecord has_one_attached :avatar, service: :s3 end </code></pre> <button class="clipboard-button" data-clipboard-text="class User < ApplicationRecord has_one_attached :avatar, service: :s3 end ">Copy</button> </div> Without <code>config/storage/test.yml</code>, the <code>s3</code> service configured in <code>config/storage.yml</code> is used - even when running tests.The default configuration would be used and files would be uploaded to the service provider configured in <code>config/storage.yml</code>.In this case, you can add <code>config/storage/test.yml</code> and use Disk service for <code>s3</code> service to prevent sending requests.<div class="interstitial code"> <pre><code class="highlight yaml">test: service: Disk root: <%= Rails.root.join("tmp/storage") %> s3: service: Disk root: <%= Rails.root.join("tmp/storage") %> </code></pre> <button class="clipboard-button" data-clipboard-text="test: service: Disk root: <%= Rails.root.join("tmp/storage") %> s3: service: Disk root: <%= Rails.root.join("tmp/storage") %> ">Copy</button> </div> <h2 id="implementing-support-for-other-cloud-services"><a class="anchorlink" href="#implementing-support-for-other-cloud-services" data-turbo="false">11 Implementing Support for Other Cloud Services</a></h2>If you need to support a cloud service other than these, you will need to implement the Service. Each service extends <a href="https://api.rubyonrails.org/v8.0.0/classes/ActiveStorage/Service.html"><code>ActiveStorage::Service</code></a> by implementing the methods necessary to upload and download files to the cloud.<h2 id="purging-unattached-uploads"><a class="anchorlink" href="#purging-unattached-uploads" data-turbo="false">12 Purging Unattached Uploads</a></h2>There are cases where a file is uploaded but never attached to a record. This can happen when using <a href="#direct-uploads">Direct Uploads</a>. You can query for unattached records using the <a href="https://github.com/rails/rails/blob/8ef5bd9ced351162b673904a0b77c7034ca2bc20/activestorage/app/models/active_storage/blob.rb#L49">unattached scope</a>. Below is an example using a <a href="command_line.html#custom-rake-tasks">custom rake task</a>.<div class="interstitial code"> <pre><code class="highlight ruby">namespace :active_storage do desc "Purges unattached Active Storage blobs. Run regularly." task purge_unattached: :environment do ActiveStorage::Blob.unattached.where(created_at: ..2.days.ago).find_each(&:purge_later) end end </code></pre> <button class="clipboard-button" data-clipboard-text="namespace :active_storage do desc "Purges unattached Active Storage blobs. Run regularly." task purge_unattached: :environment do ActiveStorage::Blob.unattached.where(created_at: ..2.days.ago).find_each(&:purge_later) end end ">Copy</button> </div> <div class="interstitial warning">The query generated by <code>ActiveStorage::Blob.unattached</code> can be slow and potentially disruptive on applications with larger databases.</div> </section> <hr> <footer aria-labelledby="heading-feedback" role="region"> <h2 id="heading-feedback">Feedback</h2> You're encouraged to help improve the quality of this guide. Please contribute if you see any typos or factual errors. To get started, you can read our <a href="https://edgeguides.rubyonrails.org/contributing_to_ruby_on_rails.html#contributing-to-the-rails-documentation">documentation contributions</a> section. You may also find incomplete content or stuff that is not up to date. Please do add any missing documentation for main. Make sure to check <a href="https://edgeguides.rubyonrails.org">Edge Guides</a> first to verify if the issues are already fixed or not on the main branch. Check the <a href="ruby_on_rails_guides_guidelines.html">Ruby on Rails Guides Guidelines</a> for style and conventions. If for whatever reason you spot something to fix but cannot patch it yourself, please <a href="https://github.com/rails/rails/issues">open an issue</a>. And last but not least, any kind of discussion regarding Ruby on Rails documentation is very welcome on the <a href="https://discuss.rubyonrails.org/c/rubyonrails-docs">official Ruby on Rails Forum</a>. </footer> </div> </article> </main> <hr class="hide" /> <footer id="complementary"> <div class="wrapper"> This work is licensed under a <a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative Commons Attribution-ShareAlike 4.0 International</a> License "Rails", "Ruby on Rails", and the Rails logo are trademarks of David Heinemeier Hansson. All rights reserved. </div> </footer> <a href="#main-skip-link" class="back-to-top" data-turbo="false">Back to top</a> </body> </html>