Build a Rails app on floo

From a Rails 7+ project on GitHub to a live app at https://<app>.on.getfloo.com, with managed Postgres, signed-in users, and your own domain. New to floo? Start with the Quickstart.

Before you start

You need:

A Rails 7+ project (or a fresh rails new).
The project pushed to a GitHub repository (public or private). floo pulls source from GitHub; it does not upload local files.
The floo CLI installed and authenticated (curl -fsSL https://getfloo.com/install.sh | bash then floo auth login).
The floo GitHub App installed on the account that owns the repository. floo apps github connect opens a browser to install it if it is missing.

1. Add a Dockerfile

Rails 7.1+ ships with a production-ready Dockerfile from rails new. If yours doesn’t, generate one:

bin/rails generate dockerfile

Or write a minimal one:

Dockerfile

FROM ruby:3.3-slim

ENV RAILS_ENV=production
ENV RAILS_LOG_TO_STDOUT=1
ENV RAILS_SERVE_STATIC_FILES=1

RUN apt-get update -qq && \
    apt-get install -y --no-install-recommends \
      build-essential libpq-dev libyaml-dev && \
    rm -rf /var/lib/apt/lists/*

WORKDIR /app

COPY Gemfile Gemfile.lock ./
RUN bundle config set --local without 'development test' && \
    bundle install --jobs 4

COPY . .
RUN SECRET_KEY_BASE_DUMMY=1 bundle exec rails assets:precompile

CMD ["sh", "-c", "bin/rails server -b 0.0.0.0 -p $PORT"]

RAILS_ENV=production is set before assets:precompile so the production asset pipeline runs, and SECRET_KEY_BASE_DUMMY=1 lets Rails 7.1+ precompile without the real secret, which is not available at build time.

Bind to 0.0.0.0 on $PORT, not localhost on a fixed port. floo sets PORT at runtime and only routes traffic to processes bound to all interfaces.

2. Initialize the floo config

From the repo root:

floo init my-rails-app

This writes floo.app.toml. For a single-service Rails app it looks like:

floo.app.toml

[app]
name = "my-rails-app"

[services.web]
type = "web"
path = "."
port = 3000
ingress = "public"
dev_command = "bin/rails server -p 3000"
migrate_command = "bin/rails db:migrate"

migrate_command runs as a one-off job with the new image before traffic shifts, on every dev deploy and every promote; a failed migration is logged as a warning and the rollout continues, except on a promote that reuses the dev image (no NEXT_PUBLIC_/VITE_/REACT_APP_ vars in prod), where it fails the promote before prod changes.

3. Connect the repo and deploy

floo preflight
git add . && git commit -m "feat: floo config + Dockerfile"
git push origin main
floo apps github connect owner/my-rails-app

github connect does three things:

Creates the floo app if it doesn’t exist.
Wires the GitHub repo as the source.
Triggers the first deploy.

Watch the build:

floo deploys watch --app my-rails-app

When it’s done:

floo apps show my-rails-app

Your Rails app is live at https://my-rails-app-dev.on.getfloo.com.Every git push origin main ships to dev. floo releases promote --app my-rails-app publishes to https://my-rails-app.on.getfloo.com.

4. Add a Postgres database

floo.app.toml

[managed.default]
type = "postgres"

This declaration provisions the database on the next deploy and injects DATABASE_URL plus standard PG* component variables. Commit it so reviewers see managed-service intent alongside code:

floo preflight
git add floo.app.toml && git commit -m "feat: add postgres"
git push origin main

Rails reads DATABASE_URL automatically. Confirm config/database.yml has the production block:

config/database.yml

production:
  primary:
    url: <%= ENV["DATABASE_URL"] %>

The next deploy runs bin/rails db:migrate against the new database before traffic shifts. Dev and prod each get isolated schemas and credentials: no shared state, no cross-environment leaks. DATABASE_URL is a normal PostgreSQL URI, so Rails/ActiveRecord can parse it directly. You do not need custom socket parsing in config/database.yml. floo preflight also warns if a local env file still contains the old socket-style DATABASE_URL shape (postgresql://user:pass@/db?host=/cloudsql/...), which Ruby’s URI parser rejects before Rails can boot. Need embeddings? Managed Postgres ships with pgvector enabled, declare a bare vector column (t.vector :embedding, limit: 1536, or the neighbor gem) with no CREATE EXTENSION step. See Postgres → Vector search.

5. Add Redis (cache, jobs, Action Cable)

floo.app.toml

[managed.cache]
type = "redis"

Run preflight, commit, and push the declaration before using the generated credentials. This injects REDIS_URL_CACHE (a rediss:// URL). One instance can back Rails cache, Sidekiq, and Action Cable at once:

config/environments/production.rb

config.cache_store = :redis_cache_store, { url: ENV["REDIS_URL_CACHE"] }

config/initializers/sidekiq.rb

Sidekiq.configure_server { |c| c.redis = { url: ENV["REDIS_URL_CACHE"] } }
Sidekiq.configure_client { |c| c.redis = { url: ENV["REDIS_URL_CACHE"] } }

config/cable.yml

production:
  adapter: redis
  url: <%= ENV["REDIS_URL_CACHE"] %>

Rails namespaces cache keys, Sidekiq uses its own prefixes, and Action Cable uses pub/sub channels, so they coexist on one instance without collision. Enqueue here, run there. Run Sidekiq as its own floo service that attaches the same Redis. Both web and worker declare redis:cache, so floo injects the same REDIS_URL_CACHE into both. A worker takes no HTTP traffic, but floo preflight still requires a port on every inline service, so declare one and leave ingress internal. Because the worker shares the web build, it must also declare its own command:

floo.app.toml

[services.web.env]
managed = ["postgres", "redis:cache"]

[services.worker]
type = "worker"
path = "."
port = 3001
command = "bundle exec sidekiq"

[services.worker.env]
managed = ["postgres", "redis:cache"]

Want cache and queue on physically separate instances? Declare named ones ([managed.cache], [managed.queue]) and read REDIS_URL_CACHE / REDIS_URL_QUEUE. See Redis.

6. Add file storage (Active Storage)

floo.app.toml

[managed.uploads]
type = "storage"

Run preflight, commit, and push the declaration before using the bucket. This injects STORAGE_BUCKET_UPLOADS. Attach it with managed = ["storage:uploads"]. floo runs your container as a service account with read/write on that bucket, so Active Storage’s google service authenticates automatically via Application Default Credentials, with no key file or project::

config/storage.yml

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

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). floo grants the app read/write but not URL-signing, so Active Storage’s default redirect-mode serving and browser direct uploads won’t work, proxy mode streams blobs through your app and has_one_attached uploads go through your controllers, both server-side and signing-free. Don’t use Active Storage :amazon / S3 SDKs; floo mints no S3 keys. Full contract: Cloud storage.

7. Add per-user auth

floo manages user authentication for you. Set access_mode = "accounts" in floo.app.toml:

floo.app.toml

[app]
name = "my-rails-app"
access_mode = "accounts"

Push and deploy. From the next deploy onward, floo’s gateway sits in front of your app and:

Redirects unauthenticated requests to a hosted login page.
Validates the session cookie on every request.
Injects identity headers into every request that reaches your Rails app.

Your Rails controllers read the headers: no auth code, no callback handlers, no session storage:

app/controllers/application_controller.rb

class ApplicationController < ActionController::Base
  before_action :load_floo_user

  private

  def load_floo_user
    @current_user_email = request.headers["X-Floo-User-Email"]
    @current_user_id    = request.headers["X-Floo-User-Id"]
    @current_user_name  = request.headers["X-Floo-User-Name"]
  end
end

For local development, run floo dev --fixture-user (see section 9), it injects the same X-Floo-User-* headers floo’s gateway adds in production, so the controller above works locally without any conditional code. For the full reference on access modes and identity headers, see Auth.

8. Add a custom domain

floo domains add app.example.com --app my-rails-app

Add the records the command prints at your DNS provider: a CNAME from app.example.com to edge.getfloo.com and the _floo-verify TXT claim token. Once they propagate, click Verify DNS in the dashboard or run floo domains verify app.example.com --app my-rails-app. If your app needs request.host to match the custom domain (for redirects, mailer URLs, etc.), Rails reads it from the Host header automatically: no extra config needed.

9. Local development with dev credentials

Once your first deploy is up, you don’t need to redeploy to iterate. Two commands cover the daily Rails workflow.

Local dev server

floo dev --app my-rails-app

Runs dev_command (the bin/rails server line in floo.app.toml) locally with DATABASE_URL and the other env vars from the app’s dev environment: a real connection to your dev Postgres from your laptop, with no credentials in your shell history. Prod credentials are never handed to a local session. To test signed-in flows without writing a fixture-user shim in your Rails code, add --fixture-user:

floo dev --app my-rails-app --fixture-user you@example.com

floo dev then starts a small proxy in front of each accounts-mode service that injects the same X-Floo-User-* headers floo’s gateway adds in production. The output table shows both the raw service URL and the auth-proxied URL. Hit the auth-proxied one when testing dashboard/profile/etc. paths.

One-shot commands: rake tasks, console, db:seed

floo run executes a single command with the same dev-environment env vars floo dev injects: no server, only the command. Pass the command after --:

# Run a rake task against your dev database
floo run --service web -- bundle exec rake my_task

# Seed the dev database
floo run --service web -- bin/rails db:seed

# Open a Rails console connected to dev Postgres
floo run --service web -- bin/rails console

# Run a migration manually (outside the deploy path)
floo run --service web -- bin/rails db:migrate

floo run inherits stdin/stdout/stderr, so interactive commands like bin/rails console and byebug work the same as running them locally, the only difference is your shell sees the floo-injected env vars instead of whatever’s in your local .env.

Migrations run automatically on every deploy via migrate_command in floo.app.toml. Use floo run -- bin/rails db:migrate only for ad-hoc migration work outside the deploy path.

Common gotchas

/healthz is reserved. floo’s edge intercepts that exact path. Use /health or /livez for health checks.
bind: 0.0.0.0, not localhost. Rails binds to localhost by default in some configs, which floo cannot reach.
Asset compilation. RAILS_SERVE_STATIC_FILES=1 is set in the Dockerfile above so Rails serves precompiled assets directly. For high-traffic apps, push assets to floo’s storage service or a CDN.
Force-SSL. Rails 7+ defaults config.force_ssl = true in production. floo’s edge handles TLS termination and forwards X-Forwarded-Proto: https, so this works correctly without extra config.
Schema dumps. Each environment gets its own Postgres schema (app_<id>_dev / _prod); the search_path resolves your unqualified table names, so migrations need no changes. If you switch to config.active_record.schema_format = :sql, keep migrations schema-agnostic, a structure.sql dumped from one environment embeds that environment’s schema name. The default :ruby format (schema.rb) avoids this.

What’s next

Auth, full reference

Identity headers, access policies, and access modes in detail.

Managed services

Postgres, Redis, Storage: what they cost and how isolation works.

Custom domains

DNS, verification, multi-service routing.

Environments

Dev vs prod, promotion, env overrides.

Get started

Build with your stack

Deploy

Managed services

Environments

Operate

Access

For agents

Build a Rails app on floo

Before you start

1. Add a Dockerfile

2. Initialize the floo config

3. Connect the repo and deploy

4. Add a Postgres database

5. Add Redis (cache, jobs, Action Cable)

6. Add file storage (Active Storage)

7. Add per-user auth

8. Add a custom domain

9. Local development with dev credentials

Local dev server

One-shot commands: rake tasks, console, db:seed

Common gotchas

What’s next

Auth, full reference

Managed services

Custom domains

Environments

​Before you start

​1. Add a Dockerfile

​2. Initialize the floo config

​3. Connect the repo and deploy

​4. Add a Postgres database

​5. Add Redis (cache, jobs, Action Cable)

​6. Add file storage (Active Storage)

​7. Add per-user auth

​8. Add a custom domain

​9. Local development with dev credentials

​Local dev server

​One-shot commands: rake tasks, console, db:seed

​Common gotchas

​What’s next

Auth, full reference

Managed services

Custom domains

Environments

Before you start

1. Add a Dockerfile

2. Initialize the floo config

3. Connect the repo and deploy

4. Add a Postgres database

5. Add Redis (cache, jobs, Action Cable)

6. Add file storage (Active Storage)

7. Add per-user auth

8. Add a custom domain

9. Local development with dev credentials

Local dev server

One-shot commands: rake tasks, console, db:seed

Common gotchas

What’s next