In a Rails 8.1 app, what does config/storage.yml declare, and how does each environment choose its Active Storage service?
answer
- top-level keys are service names
- service: Disk, S3, GCS or Mirror
- config.active_storage.service per environment
- blob rows remember service_name
- :azure removed in 8.1
basics
~20 sconfig/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 linestest:
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
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.
Explain service_name on each blob, per-attachment service: overrides, config/storage/production.yml precedence and the client gems the cloud adapters need.
Plan production storage: credentials outside the file, bucket names per environment, client timeouts, and what a service switch does to existing blobs.
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.