Add docs for CDN in front of ActiveStorage [ci skip]

Co-authored-by: Bruno Vezoli <brunvezoli@hotmail.com>
Co-authored-by: Juan Eduardo Roig <jeroig@gmail.com>

activestorage/README.md

@@ -124,19 +124,19 @@ When the application is configured to proxy files by default, use the `rails_sto
 
 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.
 
-Explicitly proxy attachments using the `rails_storage_proxy_path` and `_url` route helpers:
-
-```erb
-<%= image_tag rails_storage_proxy_path(@user.avatar) %>
-```
-
-Or configure Active Storage to use proxying by default:
+You can configure Active Storage to use proxying by default:
 
 ```ruby
 # config/initializers/active_storage.rb
 Rails.application.config.active_storage.resolve_model_to_route = :rails_storage_proxy
 ```
 
+Or if you want to explicitly proxy specific attachments there are URL helpers you can use in the form of `rails_storage_proxy_path` and `rails_storage_proxy_url`.
+
+```erb
+<%= image_tag rails_storage_proxy_path(@user.avatar) %>
+```
+
 ## Direct uploads
 
 Active Storage, with its included JavaScript library, supports uploading directly from the client to the cloud.

guides/source/active_storage_overview.md

@@ -548,6 +548,61 @@ jobs, Cronjobs, etc.), you can access the `rails_blob_path` like this:
 Rails.application.routes.url_helpers.rails_blob_path(user.avatar, only_path: true)
 ```
 
+### Proxy mode
+
+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:
+
+```ruby
+# config/initializers/active_storage.rb
+Rails.application.config.active_storage.resolve_model_to_route = :rails_storage_proxy
+```
+
+Or if you want to explicitly proxy specific attachments there are URL helpers you can use in the form of `rails_storage_proxy_path` and `rails_storage_proxy_url`.
+
+```erb
+<%= image_tag rails_storage_proxy_path(@user.avatar) %>
+```
+
+#### Putting a CDN in front of Active Storage
+
+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 `config/routes.rb` file so that you can generate the proper URLs for the attachments and their variations. As an example, you could add this:
+
+```ruby
+# config/routes.rb
+direct :cdn_image do |model, options|
+  if model.respond_to?(:signed_id)
+    route_for(
+      :rails_service_blob_proxy,
+      model.signed_id,
+      model.filename,
+      options.merge(host: ENV['CDN_HOST'])
+    )
+  else
+    signed_blob_id = model.blob.signed_id
+    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
+```
+
+and then generate routes like this:
+
+```erb
+<%= cdn_image_url(user.avatar.variant(resize_to_limit: [128, 128])) %>
+```
+
 Downloading Files
 -----------------