Build a FastAPI app on floo

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

1. Add a Dockerfile

This example uses requirements.txt with fastapi and uvicorn. Export locked dependencies first if your project uses another package manager. The application entry point is app/main.py with an app instance.

Dockerfile

FROM python:3.13-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 requirements.txt ./
RUN pip install -r requirements.txt

COPY . .

CMD ["sh", "-c", "uvicorn app.main:app --host 0.0.0.0 --port $PORT"]

Bind to 0.0.0.0 on $PORT, not 127.0.0.1 on a fixed port. floo sets PORT at runtime and routes only to processes bound to all interfaces. The shell-form CMD expands $PORT.

2. Initialize the floo config

Install the CLI and sign in: curl -fsSL https://getfloo.com/install.sh | bash, then floo auth login. An agent can run the same journey over the HTTP API instead, starting from getfloo.com/agents.md.

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"

After adding Postgres, set migrate_command = "alembic upgrade head" under [services.web] if you use Alembic. Include Alembic and its migrations in the image. It runs as a one-off job with the new image before traffic moves to it. A failed migration stops the deploy. Use expand-then-contract migrations to keep the schema compatible with both old and new code.

3. Connect the repo and deploy

floo builds from GitHub, not local files, so push first. floo apps github connect needs the floo GitHub App on the account that owns the repository, and opens a browser to install it if it is missing.

floo preflight
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 show my-fastapi-app

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

4. Add a Postgres database

floo.app.toml

[managed.default]
type = "postgres"

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

DATABASE_URL is injected into the runtime. With SQLAlchemy 2 and asyncpg installed, preserve TLS verification while converting the URL for the async driver:

app/db.py

import os
import ssl
from sqlalchemy.engine import make_url
from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker

url = make_url(os.environ["DATABASE_URL"])
url = url.set(drivername="postgresql+asyncpg").difference_update_query(["sslmode"])
engine = create_async_engine(
    url, pool_pre_ping=True, connect_args={"ssl": ssl.create_default_context()},
)
SessionLocal = async_sessionmaker(engine, expire_on_commit=False)

If you configured migrate_command, the next deploy runs alembic upgrade head against the new database. Dev and prod each get a separate Postgres database and credentials, with no shared state.

File storage

Add [managed.uploads] with type = "storage", attach storage:uploads, and deploy. Configure boto3 in your FastAPI app; see Cloud storage for paygo restrictions and file operations.

import os
import boto3
from botocore.config import Config
s3 = boto3.client("s3", endpoint_url=os.environ["STORAGE_S3_ENDPOINT_UPLOADS"],
    region_name=os.environ["STORAGE_S3_REGION_UPLOADS"],
    aws_access_key_id=os.environ["STORAGE_S3_ACCESS_KEY_ID_UPLOADS"],
    aws_secret_access_key=os.environ["STORAGE_S3_SECRET_ACCESS_KEY_UPLOADS"],
    config=Config(request_checksum_calculation="when_required", response_checksum_validation="when_required"))

5. Add per-user auth

Set access_mode = "accounts" and floo handles sign-in:

floo.app.toml

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

From the next deploy onward, floo’s gateway:

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.

Handlers read the headers, with no auth code, callback handlers, or 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}

Locally, run floo dev --fixture-user (see section 7) or send the headers yourself with curl -H 'X-Floo-User-Email: you@example.com' .... Access modes and identity headers in full: Auth.

6. Add a custom domain

Declare the domain in floo.app.toml:

[domains."app.example.com"]
service = "web"

Commit and push, wait for that commit’s dev deploy to go live, then release it to prod and read the DNS records:

floo releases promote --app my-fastapi-app
floo domains show app.example.com --app my-fastapi-app

Publish the traffic and certificate CNAME records that show prints, then watch activation:

floo domains watch app.example.com --app my-fastapi-app

FastAPI reads Host and X-Forwarded-Host from the request, so it needs no extra config. DNS setup and troubleshooting: Custom domains.

7. Local development with dev credentials

floo dev --app my-fastapi-app

Runs dev_command locally with DATABASE_URL and readable env vars from the app’s dev environment: a real connection to your dev Postgres, with no credentials in your shell history. Write-only secrets are withheld; supply separate local values when needed. Prod credentials never reach a local session. To test signed-in flows, add --fixture-user:

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

floo dev then puts a 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 the raw service URL and the auth-proxied URL; use the auth-proxied one for any path that reads identity headers.

Common gotchas

/healthz is reserved. floo’s edge intercepts that exact path. Use /health or /livez.
Bind to 0.0.0.0. floo cannot reach 127.0.0.1.
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. Build absolute URLs from the forwarded scheme, not request.url.scheme.

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.

Multi-service routing

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

Environments

Dev vs prod, promotion, env overrides.

Get started

Build with your stack

Deploy

Managed services

Environments

Operate

Access

For agents

Build a FastAPI app on floo

1. Add a Dockerfile

2. Initialize the floo config

3. Connect the repo and deploy

4. Add a Postgres database

File storage

5. Add per-user auth

6. Add a custom domain

7. Local development with dev credentials

Common gotchas

What’s next

Auth, full reference

Managed services

Multi-service routing

Environments

​1. Add a Dockerfile

​2. Initialize the floo config

​3. Connect the repo and deploy

​4. Add a Postgres database

​File storage

​5. Add per-user auth

​6. Add a custom domain

​7. Local development with dev credentials

​Common gotchas

​What’s next

Auth, full reference

Managed services

Multi-service routing

Environments

1. Add a Dockerfile

2. Initialize the floo config

3. Connect the repo and deploy

4. Add a Postgres database

File storage

5. Add per-user auth

6. Add a custom domain

7. Local development with dev credentials

Common gotchas

What’s next