skip to content

Storage Services & Delivery

config/storage.yml declares Disk, S3, GCS and Mirror services and each environment picks one. Interviewers ask how files reach browsers: redirect or proxy mode, expiring signed URLs and a CDN.

part ofRuby on Railsread it →
on this pageshow

explore

questions

6

In a Rails 8.1 app, what does config/storage.yml declare, and how does each environment choose its Active Storage service?

level: juniorimportance: must knowfreq 60%

answer

  1. top-level keys are service names
  2. service: Disk, S3, GCS or Mirror
  3. config.active_storage.service per environment
  4. blob rows remember service_name
  5. :azure removed in 8.1

basics

~20 s

config/storage.yml names storage services, each with an adapter (Disk, S3, GCS or Mirror) and its settings. Each config/environments file sets config.active_storage.service to one of those names, and every blob records the service it was stored on.

solid answer

~40 s

`config/storage.yml` is a YAML file, run through ERB, whose top-level keys are **service names**; each entry has a `service:` adapter (`Disk`, `S3`, `GCS` or `Mirror`) plus that adapter's settings, such as `root:` for Disk or `bucket:` and `region:` for S3. A new app defines `test` (Disk under `tmp/storage`) and `local` (Disk under `storage/`) and leaves `amazon`, `google` and `mirror` commented out. Each environment picks one with `config.active_storage.service`: the generated development and production files say `:local`, test says `:test`. A model can override it per attachment with `has_one_attached :photo, service: :inspections_s3`. Every blob stores the chosen name in `service_name`, so existing files keep reading from their original service after the setting changes. S3 and GCS need `aws-sdk-s3` or `google-cloud-storage` in the Gemfile, and Rails 8.1 removed the Azure service.

code

yaml · 14 lines
yaml
test:
  service: Disk
  root: <%= Rails.root.join("tmp/storage") %>

local:
  service: Disk
  root: <%= Rails.root.join("storage") %>

inspections_s3:
  service: S3
  access_key_id: <%= Rails.application.credentials.dig(:aws, :access_key_id) %>
  secret_access_key: <%= Rails.application.credentials.dig(:aws, :secret_access_key) %>
  region: eu-central-1
  bucket: inspection-photos-<%= Rails.env %>

go deeper

for a junior

Recall the four adapters, the generated test and local Disk entries, and that config.active_storage.service in each environment file picks a service by name.

for a middle

Explain service_name on each blob, per-attachment service: overrides, config/storage/production.yml precedence and the client gems the cloud adapters need.

for a senior

Plan production storage: credentials outside the file, bucket names per environment, client timeouts, and what a service switch does to existing blobs.

for a principal

Weigh local disk on a single host against object storage for durability, backups and scaling out, and when that decision must be made.

## The file and what it declares `config/storage.yml` lists the **storage services** an app may use. It is YAML evaluated through ERB, so credentials and environment names can be interpolated. Each top-level key is a **service name** you choose; the `service:` value inside it selects the adapter class: | `service:` value | Adapter | Typical settings | |---|---|---| | `Disk` | `ActiveStorage::Service::DiskService` | `root:` directory | | `S3` | `ActiveStorage::Service::S3Service` | `bucket:`, `region:`, credentials, `endpoint:` for S3-compatible stores, `upload:` options | | `GCS` | `ActiveStorage::Service::GCSService` | `project:`, `bucket:`, `credentials:` or `iam: true` | | `Mirror` | `ActiveStorage::Service::MirrorService` | `primary:` and `mirrors:` naming other services | Disk, S3 and GCS entries may add `public: true` to make their URLs permanent and unsigned. Rails 8.1 removed the Azure Storage adapter that 8.0 had deprecated, so only these four ship with the framework. What `rails new` generates: ```yaml test: service: Disk root: <%= Rails.root.join("tmp/storage") %> local: service: Disk root: <%= Rails.root.join("storage") %> ``` followed by commented-out `amazon` (S3), `google` (GCS) and `mirror` examples. For the S3 and GCS adapters you add the client gem yourself: `gem "aws-sdk-s3", require: false` or `gem "google-cloud-storage", require: false`. ## How an environment picks a service Nothing in `storage.yml` is tied to an environment by its key. The choice is made by **`config.active_storage.service`** in each environment file: - `config/environments/development.rb`: `config.active_storage.service = :local` - `config/environments/test.rb`: `config.active_storage.service = :test` - `config/environments/production.rb`: `config.active_storage.service = :local` as generated, which stores files on the server's own disk and therefore needs persistent storage that survives redeploys For a property-inspection product that keeps photos in a bucket, production becomes: ```ruby # config/environments/production.rb config.active_storage.service = :inspections_s3 ``` If `config/storage/production.yml` exists, Rails loads that file **instead of** `config/storage.yml` in production; it is a way to keep per-environment service definitions apart, not a replacement for the setting above. When a model declares `has_one_attached` and the app has a blobs table but no service is configured, Active Storage raises at class load with "Missing Active Storage service name", pointing you at the environment file. ## Per-attachment services The global setting is only the default. An attachment can name another service, or a proc that picks one per record: ```ruby class Inspection < ApplicationRecord has_many_attached :photos, service: :inspections_s3 has_one_attached :public_cover, service: :public_s3 end ``` The macro validates the name against `storage.yml` and raises `ArgumentError` for an unknown one. ## Why service_name matters Each row in `active_storage_blobs` has a **`service_name`** column filled when the blob is created: the attachment's `service:` if given, otherwise the global service's name. `Blob#service` resolves the adapter from that column every time. Three consequences follow: 1. Changing `config.active_storage.service` affects **new** uploads only; old blobs keep reading and deleting from the service named in their row. 2. Renaming or deleting a service key in `storage.yml` while blobs still reference it breaks those blobs. 3. Moving files between services means copying bytes **and** updating `service_name`, or keeping the old name pointing at the new location, which is what the Mirror service helps with. ## Practical conventions - Interpolate `Rails.env` into bucket names (`inspection-photos-<%= Rails.env %>`) so a staging app cannot touch production files. - Keep keys out of the file: read them from encrypted credentials with `Rails.application.credentials.dig(:aws, :access_key_id)`, or omit them and let the SDK use instance roles. - Set client timeouts and `retry_limit` on S3 entries; the guide warns that default client settings can hold connections for minutes. - Use the Disk `test` service in tests so uploads land in `tmp/storage` and can be wiped.

  • You switch production from :local to :inspections_s3. What happens to photos uploaded last month?
    Their blob rows still say `service_name: "local"`, so Active Storage keeps reading them from the server's disk through the Disk service. They do not move. To migrate them you copy the files to the bucket and update `service_name`, or run a Mirror phase, and only then remove the `local` entry.
  • Can one attachment store some records' files in a different bucket, for example by region?
    Yes. The macro's `service:` option accepts a proc that receives the record: `has_many_attached :photos, service: ->(inspection) { inspection.eu? ? :inspections_s3_eu : :inspections_s3_us }`. The proc runs when a blob is built, its result is validated against `storage.yml`, and the chosen name is saved in that blob's `service_name`.

  • Rails picks the storage.yml entry whose key matches Rails.env automatically
  • Changing config.active_storage.service moves existing files to the new service
  • A new Rails 8.1 app is configured to store production uploads in Amazon S3
  • Rails 8.1 still ships an Azure Storage service alongside S3 and GCS
  • The aws-sdk-s3 gem is bundled by Rails, so no Gemfile change is needed

Assumes Rails 8.1, where the Azure Storage service was removed (deprecated in 8.0), leaving Disk, S3, GCS and Mirror.

open as a page

In Rails, what URL does rails_blob_path or url_for give for an Active Storage file in redirect mode, and how long does it stay valid?

level: middleimportance: must knowfreq 52%

basics

~20 s

In redirect mode the helper returns a stable Rails URL containing the blob's signed_id. Requesting it makes Rails answer 302 with a signed service URL that expires after service_urls_expire_in (5 minutes); the Rails URL itself never expires unless urls_expire_in is set.

open as a page

When should Active Storage serve files in proxy mode instead of redirect mode, and what does the proxy controller do differently?

level: middleimportance: should knowfreq 38%

basics

~20 s

In proxy mode the Rails app streams each file from storage to the browser under your own domain, with public cache-forever headers. Use it for a CDN in front of files; it costs app-server time per download.

open as a page

What changes when an Active Storage service in config/storage.yml is marked public: true?

level: middleimportance: should knowfreq 30%

basics

~20 s

With public: true, blob.url returns the object's permanent, unsigned URL instead of a short-lived signed one, and S3 uploads are written with a public-read ACL. The bucket must allow public reads, and every file on that service becomes readable by anyone with its address.

open as a page

A Rails app keeps private property-inspection photos in Active Storage; how would you put a CDN in front of them without exposing them to anyone holding a link?

level: seniorimportance: should knowfreq 30%

basics

~20 s

The built-in CDN recipe (proxy routes on a CDN host) caches files publicly for anyone holding a URL. For private photos, expire signed ids at some cost to hit rate, or disable the default routes and serve through an authorizing controller.

open as a page

How do you use Active Storage's Mirror service to move a live Rails app's files from one storage service to another?

level: seniorimportance: nice to knowfreq 22%

basics

~20 s

Define a Mirror service whose primary is the current store and whose mirrors include the new one, make it the active service, backfill existing blobs with mirror_later, verify the copies, then switch to the new service.

open as a page