Managed Storage on floo

Use this guide when your app needs object storage for uploads, generated assets, or other blobs.

1. Provision The Bucket

floo services add storage --app my-app

The command is idempotent — re-running is safe. It provisions a private GCS bucket, injects STORAGE_BUCKET and STORAGE_URL into your app’s environment, and updates .floo/services.lock. Commit the lock file alongside other changes. 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
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 as a dedicated per-app service account that already holds read/write (roles/storage.objectAdmin) 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 service account automatically through Application Default Credentials (ADC) on Cloud Run. 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 GCS 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 — project + credentials from the runtime
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 — project + credentials from the runtime
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 — project + credentials from the runtime
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 Doesn’t)

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 GCS SDK (sections 4–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 GCS 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 GCS 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 --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 Setup

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...

Build your app

Environments

Managed Services

Observe

Access

For Agents

Managed Storage on floo

1. Provision 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 Doesn’t)

6. Debugging Checklist

Managed Services Setup

Build a Rails app

​1. Provision 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 Doesn’t)

​6. Debugging Checklist

Managed Services Setup

Build a Rails app

1. Provision 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 Doesn’t)

6. Debugging Checklist