Storage

1. Declare the bucket

floo.app.toml

[managed.default]
type = "storage"

The next deploy provisions a private bucket and injects STORAGE_BUCKET and STORAGE_URL. Commit the declaration with the rest of your app config. Dev and prod get separate buckets, STORAGE_BUCKET differs per environment, so they never share object state. See Managed services: dev and prod isolation.

2. Ship the first deploy

floo preflight --json
git add floo.app.toml && git commit -m "feat: add managed storage"
git push origin main
floo apps github connect owner/repo --app my-app
floo deploys watch --app my-app

The first deploy bakes the storage env vars into the runtime.

3. How your app authenticates

floo runs your container under a dedicated per-app identity that already holds read and write access on your bucket, and only your bucket. So your app reaches storage directly with the native Google Cloud Storage SDK: the SDK picks up that identity automatically through Application Default Credentials (ADC). You do not manage a key file, a JSON credential, or a project id. The only value your code needs is the bucket name:

floo env get STORAGE_BUCKET --app my-app

4. Read and write objects

Use the native SDK for your language with STORAGE_BUCKET. No credentials are passed in code. ADC supplies them at runtime.

require "google/cloud/storage"

storage = Google::Cloud::Storage.new          # ADC supplies project and credentials
bucket  = storage.bucket(ENV["STORAGE_BUCKET"])

# Write
bucket.create_file(StringIO.new("hello"), "uploads/note.txt", content_type: "text/plain")

# Read
data = bucket.file("uploads/note.txt").download.read

import os
from google.cloud import storage   # pip install google-cloud-storage

client = storage.Client()                      # ADC supplies project and credentials
bucket = client.bucket(os.environ["STORAGE_BUCKET"])

# Write
bucket.blob("uploads/note.txt").upload_from_string("hello", content_type="text/plain")

# Read
data = bucket.blob("uploads/note.txt").download_as_bytes()

const { Storage } = require("@google-cloud/storage"); // npm i @google-cloud/storage

const storage = new Storage();                 // ADC supplies project and credentials
const bucket = storage.bucket(process.env.STORAGE_BUCKET);

// Write
await bucket.file("uploads/note.txt").save("hello", { contentType: "text/plain" });

// Read
const [data] = await bucket.file("uploads/note.txt").download();

5. Rails Active Storage

Point Active Storage at the google service. There is no credentials: and no project:, both come from ADC at runtime:

config/storage.yml

google:
  service: GCS
  bucket: <%= ENV["STORAGE_BUCKET"] %>

config/environments/production.rb

config.active_storage.service = :google
config.active_storage.resolve_model_to_route = :rails_storage_proxy

Use proxy mode (rails_storage_proxy, above): Rails streams blobs through your app with the SDK, and uploads go through your controllers (has_one_attached + a normal form post). Both are server-side and need no URL signing, the next section explains why that matters.

What floo Storage grants and what it does not

floo grants your app read/write on its bucket, but deliberately not URL-signing, the permission a compromised container could abuse to mint links to any object. That boundary shapes what works:

✅ Server-side read/write with the SDK (sections 4 and 5).
✅ Rails proxy-mode serving (rails_storage_proxy) and controller uploads (has_one_attached).
❌ App-generated signed URLs, browser direct uploads, and Active Storage redirect-mode serving (rails_blob_url redirecting to a signed URL). All need signing the app isn’t granted; proxy mode + server-side uploads cover the same use cases.
❌ S3-compatible SDKs (aws-sdk-s3, Active Storage :amazon). floo mints no S3/HMAC keys, use the native SDK / Active Storage :google.

STORAGE_URL is a floo operator endpoint: the dashboard and CLI call it with an admin key to mint short-lived signed URLs. It is not your app’s runtime path to storage, your app authenticates with the SDK as above, never by calling STORAGE_URL.

6. Debugging checklist

If reads or writes fail:

floo env get STORAGE_BUCKET --app my-app
floo logs query --app my-app --error --since 30m

Look for:

a missing STORAGE_BUCKET, confirm storage is in this service’s managed = [...] attachment
a 403 / permission error, the SDK isn’t using ADC; don’t pass an explicit key file, let the runtime supply credentials
code trying to sign a URL or use an S3 client, unsupported (see above), switch to proxy-mode serving and the native SDK

Managed services

See how storage and other managed services are provisioned.

Build a Rails app

End-to-end Rails on floo, including Active Storage.

Get started

Build with your stack

Deploy

Managed services

Environments

Operate

Access

For agents

1. Declare the bucket

2. Ship the first deploy

3. How your app authenticates

4. Read and write objects

5. Rails Active Storage

What floo Storage grants and what it does not

6. Debugging checklist

Managed services

Build a Rails app

​1. Declare the bucket

​2. Ship the first deploy

​3. How your app authenticates

​4. Read and write objects

​5. Rails Active Storage

​What floo Storage grants and what it does not

​6. Debugging checklist

Managed services

Build a Rails app

1. Declare the bucket

2. Ship the first deploy

3. How your app authenticates

4. Read and write objects

5. Rails Active Storage

What floo Storage grants and what it does not

6. Debugging checklist