Skip to main content

Documentation Index

Fetch the complete documentation index at: https://getfloo.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks a FastAPI app from local code to a production URL with a database and per-user auth. Every step has runnable Python code. By the end you have a working app at https://<app>.on.getfloo.com with a Postgres sibling service, signed-in users, and (optionally) your own domain. If you’ve never deployed to floo before, read Golden Path first for the minimal three-command flow.

​
Before you start

You need:
  • A FastAPI project (or a fresh uv init / poetry new).
  • The project pushed to a GitHub repository. 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 your repo’s org.

​
1. Add a Dockerfile

Dockerfile
FROM python:3.12-slim

ENV PYTHONUNBUFFERED=1 \
    PIP_NO_CACHE_DIR=1 \
    PIP_DISABLE_PIP_VERSION_CHECK=1

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

WORKDIR /app

COPY pyproject.toml uv.lock* requirements*.txt ./
RUN if [ -f uv.lock ]; then \
      pip install uv && uv export --no-dev --frozen > requirements.txt; \
    fi && \
    pip install -r requirements.txt

COPY . .

EXPOSE 8000
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
Bind to 0.0.0.0, not 127.0.0.1. Cloud Run only routes traffic to processes bound to all interfaces.

​
2. Initialize the floo config

floo init my-fastapi-app
For a single-service FastAPI app:
floo.app.toml
[app]
name = "my-fastapi-app"

[services.web]
type = "web"
path = "."
port = 8000
ingress = "public"
dev_command = "uvicorn app.main:app --reload --port 8000"
migrate_command = "alembic upgrade head"
migrate_command is optional — set it if you use Alembic. It runs after every deploy (against dev) and after every promote (against prod).

​
3. Connect the repo and deploy

git add . && git commit -m "feat: floo config + Dockerfile"
git push origin main
floo apps github connect owner/my-fastapi-app
floo deploys watch --app my-fastapi-app
When the deploy is green: 
floo apps status my-fastapi-app
Your FastAPI app is live at https://my-fastapi-app-dev.on.getfloo.com.Every git push origin main ships to dev. floo releases promote --app my-fastapi-app publishes to https://my-fastapi-app.on.getfloo.com.

​
4. Add a Postgres database

floo services add postgres --app my-fastapi-app
git add .floo/services.lock && git commit -m "feat: add postgres"
git push origin main
DATABASE_URL is injected into the runtime. Read it with SQLAlchemy:
app/db.py
import os
from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker

DATABASE_URL = os.environ["DATABASE_URL"].replace("postgresql://", "postgresql+asyncpg://", 1)
engine = create_async_engine(DATABASE_URL, pool_pre_ping=True)
SessionLocal = async_sessionmaker(engine, expire_on_commit=False)
Dev and prod each get isolated Postgres schemas and credentials — no shared state.

​
5. Add per-user auth

floo manages user authentication for you. Set access_mode = "accounts" in floo.app.toml:
floo.app.toml
[app]
name = "my-fastapi-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 FastAPI app.
Your FastAPI handlers read the headers — no auth code, no callback handlers, no session storage:
app/main.py
from fastapi import FastAPI, Header
from typing import Annotated

app = FastAPI()

@app.get("/me")
async def me(
    email: Annotated[str | None, Header(alias="X-Floo-User-Email")] = None,
    user_id: Annotated[str | None, Header(alias="X-Floo-User-Id")] = None,
    name: Annotated[str | None, Header(alias="X-Floo-User-Name")] = None,
):
    return {"email": email, "id": user_id, "name": name}
Or build a dependency that requires a signed-in user:
app/auth.py
from fastapi import Header, HTTPException, status
from typing import Annotated

class FlooUser:
    def __init__(self, email: str, user_id: str, name: str | None):
        self.email = email
        self.id = user_id
        self.name = name

def require_user(
    email: Annotated[str | None, Header(alias="X-Floo-User-Email")] = None,
    user_id: Annotated[str | None, Header(alias="X-Floo-User-Id")] = None,
    name: Annotated[str | None, Header(alias="X-Floo-User-Name")] = None,
) -> FlooUser:
    if not email or not user_id:
        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED)
    return FlooUser(email=email, user_id=user_id, name=name)
Use it on any route: 
from fastapi import Depends

@app.get("/dashboard")
async def dashboard(user: Annotated[FlooUser, Depends(require_user)]):
    return {"hello": user.email}
For local development, send the headers yourself with curl -H 'X-Floo-User-Email: you@example.com' ... or wrap the dependency to return a fixture user when the headers are missing. For the full reference on access modes and identity headers, see Add User Auth to Your App.

​
6. Add a custom domain

floo domains add app.example.com --app my-fastapi-app
Add the CNAME shown in the output at your DNS provider. FastAPI doesn’t need any extra config — it reads the Host and X-Forwarded-Host headers from the request.

​
7. Local development with prod data

floo dev --app my-fastapi-app --service web
Runs dev_command locally with DATABASE_URL and other env vars sourced from your dev floo app — real Cloud SQL connection, no credentials in your shell history. To also test signed-in flows for this accounts-mode app, add --fixture-user: 
floo dev --app my-fastapi-app --service web --fixture-user you@example.com
floo dev then starts a small proxy in front of each 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 for any path that reads identity headers.

​
Common gotchas

  • /healthz is reserved. Cloud Run’s edge intercepts that exact path. Use /health or /livez.
  • Bind to 0.0.0.0. 127.0.0.1 won’t accept Cloud Run traffic.
  • Async DB drivers. Use asyncpg for async SQLAlchemy. Use psycopg2-binary for sync. Don’t mix.
  • X-Forwarded-Proto. floo’s edge terminates TLS and forwards X-Forwarded-Proto: https. If you build absolute URLs from request.url.scheme, use the forwarded scheme instead.

​
What’s next

Add User Auth — full reference

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

Managed Services

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

Multi-Service Routing

Deploy a React or Next.js frontend alongside FastAPI with shared origin.

Environments

Dev vs prod, promotion, env overrides.