**DO NOT READ THIS FILE ON GITHUB, GUIDES ARE PUBLISHED ON https://guides.rubyonrails.org.** Active Storage Overview ======================= This 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. -------------------------------------------------------------------------------- What is Active Storage? ----------------------- 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 with [ImageMagick](https://www.imagemagick.org), generate image representations of non-image uploads like PDFs and videos, and extract metadata from arbitrary files. ## Setup Active Storage uses two tables in your application’s database named `active_storage_blobs` and `active_storage_attachments`. After creating a new application (or upgrading your application to Rails 5.2), run `bin/rails active_storage:install` to generate a migration that creates these tables. Use `bin/rails db:migrate` to run the migration. WARNING: `active_storage_attachments` is a polymorphic join table that stores your model's class name. If your model's class name changes, you will need to run a migration on this table to update the underlying `record_type` to your model's new class name. WARNING: If you are using UUIDs instead of integers as the primary key on your models you will need to change the column type of `active_storage_attachments.record_id` and `active_storage_variant_records.id` in the generated migration accordingly. Declare Active Storage services in `config/storage.yml`. For each service your application uses, provide a name and the requisite configuration. The example below declares three services named `local`, `test`, and `amazon`: ```yaml local: service: Disk root: <%= Rails.root.join("storage") %> test: service: Disk root: <%= Rails.root.join("tmp/storage") %> amazon: service: S3 access_key_id: "" secret_access_key: "" bucket: "" region: "" # e.g. 'us-east-1' ``` Tell Active Storage which service to use by setting `Rails.application.config.active_storage.service`. 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 `config/environments/development.rb`: ```ruby # Store files locally. config.active_storage.service = :local ``` To use the S3 service in production, you add the following to `config/environments/production.rb`: ```ruby # Store files on Amazon S3. config.active_storage.service = :amazon ``` To use the test service when testing, you add the following to `config/environments/test.rb`: ```ruby # Store uploaded files on the local file system in a temporary directory. config.active_storage.service = :test ``` Continue reading for more information on the built-in service adapters (e.g. `Disk` and `S3`) and the configuration they require. NOTE: Configuration files that are environment-specific will take precedence: in production, for example, the `config/storage/production.yml` file (if existent) will take precedence over the `config/storage.yml` file. ### Disk Service Declare a Disk service in `config/storage.yml`: ```yaml local: service: Disk root: <%= Rails.root.join("storage") %> ``` ### S3 Service (Amazon S3 and S3-compatible APIs) To connect to Amazon S3, declare an S3 service in `config/storage.yml`: ```yaml amazon: service: S3 access_key_id: "" secret_access_key: "" region: "" bucket: "" ``` Optionally provide client and upload options: ```yaml amazon: service: S3 access_key_id: "" secret_access_key: "" region: "" bucket: "" http_open_timeout: 0 http_read_timeout: 0 retry_limit: 0 upload: server_side_encryption: "" # 'aws:kms' or 'AES256' ``` TIP: 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. Add the [`aws-sdk-s3`](https://github.com/aws/aws-sdk-ruby) gem to your `Gemfile`: ```ruby gem "aws-sdk-s3", require: false ``` NOTE: The core features of Active Storage require the following permissions: `s3:ListBucket`, `s3:PutObject`, `s3:GetObject`, and `s3:DeleteObject`. If you have additional upload options configured such as setting ACLs then additional permissions may be required. NOTE: If you want to use environment variables, standard SDK configuration files, profiles, IAM instance profiles or task roles, you can omit the `access_key_id`, `secret_access_key`, and `region` keys in the example above. The S3 Service supports all of the authentication options described in the [AWS SDK documentation] (https://docs.aws.amazon.com/sdk-for-ruby/v3/developer-guide/setup-config.html). To connect to an S3-compatible object storage API such as DigitalOcean Spaces, provide the `endpoint`: ```yaml digitalocean: service: S3 endpoint: https://nyc3.digitaloceanspaces.com access_key_id: ... secret_access_key: ... # ...and other options ``` ### Microsoft Azure Storage Service Declare an Azure Storage service in `config/storage.yml`: ```yaml azure: service: AzureStorage storage_account_name: "" storage_access_key: "" container: "" ``` Add the [`azure-storage-blob`](https://github.com/Azure/azure-storage-ruby) gem to your `Gemfile`: ```ruby gem "azure-storage-blob", require: false ``` ### Google Cloud Storage Service Declare a Google Cloud Storage service in `config/storage.yml`: ```yaml google: service: GCS credentials: <%= Rails.root.join("path/to/keyfile.json") %> project: "" bucket: "" ``` Optionally provide a Hash of credentials instead of a keyfile path: ```yaml 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: "" ``` Add the [`google-cloud-storage`](https://github.com/GoogleCloudPlatform/google-cloud-ruby/tree/master/google-cloud-storage) gem to your `Gemfile`: ```ruby gem "google-cloud-storage", "~> 1.11", require: false ``` ### Mirror Service 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. 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. Define each of the services you'd like to mirror as described above. Reference them by name when defining a mirror service: ```yaml s3_west_coast: service: S3 access_key_id: "" secret_access_key: "" region: "" bucket: "" s3_east_coast: service: S3 access_key_id: "" secret_access_key: "" region: "" bucket: "" production: service: Mirror primary: s3_east_coast mirrors: - s3_west_coast ``` 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. ### Public access 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 `public: true` in your app's `config/storage.yml`: ```yaml gcs: &gcs service: GCS project: "" private_gcs: <<: *gcs credentials: <%= Rails.root.join("path/to/private_keyfile.json") %> bucket: "" public_gcs: <<: *gcs credentials: <%= Rails.root.join("path/to/public_keyfile.json") %> bucket: "" public: true ``` Make sure your buckets are properly configured for public access. See docs on how to enable public read permissions for [Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/block-public-access-bucket.html), [Google Cloud Storage](https://cloud.google.com/storage/docs/access-control/making-data-public#buckets), and [Microsoft Azure](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-manage-access-to-resources#set-container-public-access-level-in-the-azure-portal) storage services. When converting an existing application to use `public: true`, make sure to update every individual file in the bucket to be publicly-readable before switching over. Attaching Files to Records -------------------------- ### `has_one_attached` The [`has_one_attached`][] 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 `User` model. If you want each user to have an avatar, define the `User` model like this: ```ruby class User < ApplicationRecord has_one_attached :avatar end ``` You can create a user with an avatar: ```erb <%= form.file_field :avatar %> ``` ```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.require(:user).permit(:email_address, :password, :avatar) end end ``` Call [`avatar.attach`][Attached::One#attach] to attach an avatar to an existing user: ```ruby user.avatar.attach(params[:avatar]) ``` Call [`avatar.attached?`][Attached::One#attached?] to determine whether a particular user has an avatar: ```ruby user.avatar.attached? ``` In some cases you might want to override a default service for a specific attachment. You can configure specific services per attachment using the `service` option: ```ruby class User < ApplicationRecord has_one_attached :avatar, service: :s3 end ``` You can configure specific variants per attachment by calling the `variant` method on yielded attachable object: ```ruby class User < ApplicationRecord has_one_attached :avatar do |attachable| attachable.variant :thumb, resize: "100x100" end end ``` Call `avatar.variant(:thumb)` to get a thumb variant of an avatar: ```erb <%= image_tag user.avatar.variant(:thumb) %> ``` [`has_one_attached`]: https://api.rubyonrails.org/classes/ActiveStorage/Attached/Model.html#method-i-has_one_attached [Attached::One#attach]: https://api.rubyonrails.org/classes/ActiveStorage/Attached/One.html#method-i-attach [Attached::One#attached?]: https://api.rubyonrails.org/classes/ActiveStorage/Attached/One.html#method-i-attached-3F ### `has_many_attached` The [`has_many_attached`][] 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 `Message` model. If you want each message to have many images, define the `Message` model like this: ```ruby class Message < ApplicationRecord has_many_attached :images end ``` You can create a message with images: ```ruby class MessagesController < ApplicationController def create message = Message.create!(message_params) redirect_to message end private def message_params params.require(:message).permit(:title, :content, images: []) end end ``` Call [`images.attach`][Attached::Many#attach] to add new images to an existing message: ```ruby @message.images.attach(params[:images]) ``` Call [`images.attached?`][Attached::Many#attached?] to determine whether a particular message has any images: ```ruby @message.images.attached? ``` Overriding the default service is done the same way as `has_one_attached`, by using the `service` option: ```ruby class Message < ApplicationRecord has_many_attached :images, service: :s3 end ``` Configuring specific variants is done the same way as `has_one_attached`, by calling the `variant` method on the yielded attachable object: ```ruby class Message < ApplicationRecord has_many_attached :images do |attachable| attachable.variant :thumb, resize: "100x100" end end ``` [`has_many_attached`]: https://api.rubyonrails.org/classes/ActiveStorage/Attached/Model.html#method-i-has_many_attached [Attached::Many#attach]: https://api.rubyonrails.org/classes/ActiveStorage/Attached/Many.html#method-i-attach [Attached::Many#attached?]: https://api.rubyonrails.org/classes/ActiveStorage/Attached/Many.html#method-i-attached-3F ### Attaching File/IO Objects 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: ```ruby @message.image.attach(io: File.open('/path/to/file'), filename: 'file.pdf') ``` 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. ```ruby @message.image.attach(io: File.open('/path/to/file'), filename: 'file.pdf', content_type: 'application/pdf') ``` You can bypass the content type inference from the data by passing in `identify: false` along with the `content_type`. ```ruby @message.image.attach( io: File.open('/path/to/file'), filename: 'file.pdf', content_type: 'application/pdf', identify: false ) ``` 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. Removing Files -------------- To remove an attachment from a model, call [`purge`][Attached::One#purge] on the attachment. If your application is set up to use Active Job, removal can be done in the background instead by calling [`purge_later`][Attached::One#purge_later]. Purging deletes the blob and the file from the storage service. ```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 ``` [Attached::One#purge]: https://api.rubyonrails.org/classes/ActiveStorage/Attached/One.html#method-i-purge [Attached::One#purge_later]: https://api.rubyonrails.org/classes/ActiveStorage/Attached/One.html#method-i-purge_later Linking to Files ---------------- Generate a permanent URL for the blob that points to the application. Upon access, a redirect to the actual service endpoint is returned. 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. ```ruby url_for(user.avatar) ``` WARNING: The links generated by ActiveStorage are hard to guess, but publicly accessible by default. Anyone that knows the blob URL will be able to download it, even if a `before_action` in your `ApplicationController` would otherwise require a login. If your files require a higher level of protection consider implementing your own authenticated [`ActiveStorage::Blobs::RedirectController`](https://github.com/rails/rails/blob/main/activestorage/app/controllers/active_storage/blobs/redirect_controller.rb) and [`ActiveStorage::Representations::RedirectController`](https://github.com/rails/rails/blob/main/activestorage/app/controllers/active_storage/representations/redirect_controller.rb). To create a download link, use the `rails_blob_{path|url}` helper. Using this helper allows you to set the disposition. ```ruby rails_blob_path(user.avatar, disposition: "attachment") ``` WARNING: To prevent XSS attacks, ActiveStorage forces the Content-Disposition header to "attachment" for some kind of files. To change this behaviour see the available configuration options in [Configuring Rails Applications](configuring.html#configuring-active-storage). If you need to create a link from outside of controller/view context (Background jobs, Cronjobs, etc.), you can access the `rails_blob_path` like this: ```ruby Rails.application.routes.url_helpers.rails_blob_path(user.avatar, only_path: true) ``` Downloading Files ----------------- Sometimes you need to process a blob after it’s uploaded—for example, to convert it to a different format. Use the attachment's [`download`][Blob#download] method to read a blob’s binary data into memory: ```ruby binary = user.avatar.download ``` 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 [`open`][Blob#open] method to download a blob to a tempfile on disk: ```ruby message.video.open do |file| system '/path/to/virus/scanner', file.path # ... end ``` It's important to know that the file is not yet available in the `after_create` callback but in the `after_create_commit` only. [Blob#download]: https://api.rubyonrails.org/classes/ActiveStorage/Blob.html#method-i-download [Blob#open]: https://api.rubyonrails.org/classes/ActiveStorage/Blob.html#method-i-open Analyzing Files --------------- 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 `analyzed: true`. You can check whether a blob has been analyzed by calling [`analyzed?`][] on it. Image analysis provides `width` and `height` attributes. Video analysis provides these, as well as `duration`, `angle`, and `display_aspect_ratio`. Analysis requires the `mini_magick` gem. Video analysis also requires the [FFmpeg](https://www.ffmpeg.org/) library, which you must include separately. [`analyzed?`]: https://api.rubyonrails.org/classes/ActiveStorage/Blob/Analyzable.html#method-i-analyzed-3F Displaying Images, Videos, and PDFs --------------- Active Storage supports representing a variety of files. You can call [`representation`][] on an attachment to display an image variant, or a preview of a video or PDF. Before calling `representation`, check if the attachment can be represented by calling [`representable?`]. Some file formats can't be previewed by ActiveStorage out of the box (eg. Word documents); if `representable?` returns false you may want to [link to](#linking-to-files) the file instead. ```erb