aboutsummaryrefslogtreecommitdiffstats
path: root/guides/source/active_storage_overview.md
diff options
context:
space:
mode:
authorJeffrey Guenther <guenther.jeffrey@gmail.com>2017-11-18 17:24:37 -0800
committerJeffrey Guenther <guenther.jeffrey@gmail.com>2017-11-18 17:24:37 -0800
commit6aac8fa3ec355f304d235f2e5a14a852584b6f02 (patch)
tree838edf48e2798105279b452ad4eb190dc4ecf72c /guides/source/active_storage_overview.md
parent01c9f1363cf99076802dddc6b7e01cc1cf6032c5 (diff)
downloadrails-6aac8fa3ec355f304d235f2e5a14a852584b6f02.tar.gz
rails-6aac8fa3ec355f304d235f2e5a14a852584b6f02.tar.bz2
rails-6aac8fa3ec355f304d235f2e5a14a852584b6f02.zip
Integrates George's suggestions
- Describes how to setup each of the services in the `services.yml` - Integrates copy changes
Diffstat (limited to 'guides/source/active_storage_overview.md')
-rw-r--r--guides/source/active_storage_overview.md187
1 files changed, 135 insertions, 52 deletions
diff --git a/guides/source/active_storage_overview.md b/guides/source/active_storage_overview.md
index 9c0d3d2709..04f0ccec99 100644
--- a/guides/source/active_storage_overview.md
+++ b/guides/source/active_storage_overview.md
@@ -3,83 +3,165 @@
Active Storage
==============
-This guide covers how to attach files to your ActiveRecord models.
+This guide covers how to attach files to your Active Record models.
After reading this guide, you will know:
-* How to attach a file(s) to a model.
-* How to remove the attached file.
-* How to link to the attached file.
-* How to create variations of an image.
-* How to generate a preview for files other than images.
-* How to upload files directly to a service.
-* How to implement a download link.
-* How to add support for additional cloud services.
+* 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 implement support for additional storage services.
* How to clean up files stored during testing.
--------------------------------------------------------------------------------
-Active Storage makes it simple to upload and reference files in cloud services
-like Amazon S3, Google Cloud Storage, or Microsoft Azure Storage, and attach
-those files to Active Records. Supports having one main service and mirrors in
-other services for redundancy. It also provides a disk service for testing or
-local deployments, but the focus is on cloud storage.
+What is Active Storage?
+-----------------------
-Files can be uploaded from the server to the cloud or directly from the client
-to the cloud.
+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.
-Image files can furthermore be transformed using on-demand variants for quality,
-aspect ratio, size, or any other
-[MiniMagick](https://github.com/minimagick/minimagick) supported transformation.
+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.
-## Compared to other storage solutions
+## Setup
-A key difference to how Active Storage works compared to other attachment
-solutions in Rails is through the use of built-in
-[Blob](https://github.com/rails/rails/blob/master/activestorage/app/models/active_storage/blob.rb)
-and
-[Attachment](https://github.com/rails/rails/blob/master/activestorage/app/models/active_storage/attachment.rb)
-models (backed by Active Record). This means existing application models do not
-need to be modified with additional columns to associate with files. Active
-Storage uses polymorphic associations via the `Attachment` join model, which
-then connects to the actual `Blob`.
+To setup an existing application after upgrading to Rails 5.2, run `rails
+active_storage:install`. If you're creating a new project with Rails 5.2,
+ActiveStorage will be installed by default. Installation generates a migration
+to add the tables needed to store attachments.
-`Blob` models store attachment metadata (filename, content-type, etc.), and
-their identifier key in the storage service. Blob models do not store the actual
-binary data. They are intended to be immutable in spirit. One file, one blob.
-You can associate the same blob with multiple application models as well. And if
-you want to do transformations of a given `Blob`, the idea is that you'll simply
-create a new one, rather than attempt to mutate the existing one (though of
-course you can delete the previous version later if you don't need it).
+If you wish to transform your images, add `mini_magick` to your Gemfile:
+``` ruby
+gem 'mini_magick'
+```
-## Setup
+Inside a Rails application, you can set up your services through the generated
+`config/storage.yml` file and reference one of the supported service types under
+the `service` key.
+
+### Disk Service
+To use the Disk service:
+
+``` yaml
+local:
+ service: Disk
+ root: <%= Rails.root.join("storage") %>
+```
+
+### Amazon S3 Service
+
+To use Amazon S3:
+``` yaml
+local:
+ service: S3
+ access_key_id: ""
+ secret_access_key: ""
+ region: ""
+ bucket: ""
+```
+Also, add the S3 client gem to your Gemfile:
+
+``` ruby
+gem "aws-sdk-s3", require: false
+```
+### Microsoft Azure Storage Service
+
+To use Microsoft Azure Storage:
+
+``` yaml
+local:
+ service: AzureStorage
+ path: ""
+ storage_account_name: ""
+ storage_access_key: ""
+ container: ""
+```
+
+Also, add the Microsoft Azure Storage client gem to your Gemfile:
+
+``` ruby
+gem "azure-storage", require: false
+```
+
+### Google Cloud Storage Service
+
+To use Google Cloud Storage:
+
+``` yaml
+local:
+ service: GCS
+ keyfile: {
+ type: "service_account",
+ project_id: "",
+ private_key_id: "",
+ private_key: "",
+ 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: ""
+```
+
+Also, add the S3 client gem to your Gemfile:
+
+``` ruby
+gem "google-cloud-storage", "~> 1.3", require: false
+```
-To setup an existing application after upgrading to Rails 5.2, run `rails active_storage:install`. If you're creating a new project with Rails 5.2, ActiveStorage will be installed by default. This generates the tables for the
-`Attachment` and `Blob` models.
+### Mirror Service
-Inside a Rails application, you can set-up your services through the
-generated `config/storage.yml` file and reference one
-of the aforementioned constant under the +service+ key. For example:
+You can keep multiple services in sync by defining a mirror service. When
+a file is uploaded or deleted, it's done across all the mirrored services.
+Define each of the services you'd like to use as described above and then define
+a mirrored service which references them.
``` yaml
- local:
- service: Disk
- root: <%= Rails.root.join("storage") %>
+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
```
-NOTE: Should we include the required keys for all the supported services?
-NOTE: Should we mention the mirror service and how to set it up?
-In your application's configuration, specify the service to
-use like this:
+In your application's configuration, specify the service to use like this:
``` ruby
config.active_storage.service = :local
```
-Like other configuration options, you can set the service application wide, or per
-environment. For example, you might want development and test to use the Disk
-service instead of a cloud service.
+Like other configuration options, you can set the service application wide in
+`application.rb`, or per environment in `config/environments/{environment}.rb`.
+For example, you might want development and test to use the Disk service instead
+of a cloud service.
Attach Files to a Model
--------------------------
@@ -148,6 +230,7 @@ Remove File Attached to Model
To remove an attachment from a model, call `purge` on the attachment. Removal
can be done in the background if your application is setup to use ActiveJob.
+Purging deletes the blob and the file from the storage service.
```ruby
# Synchronously destroy the avatar and actual resource files.