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

# Build a Flask app on floo

> Deploy a Flask app with Postgres, sign-in, and a custom domain.

From a Flask 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](https://getfloo.com/docs/introduction.md).

## What your agent controls

floo builds the `Dockerfile` in your repository. Add one that specifies the runtime for your app:

* The base image and the exact Python version.
* System packages, such as `ffmpeg`, Chromium for headless browsing, or `libpq`, each one `apt-get install` line.
* The build steps and the start command, including the Gunicorn worker count.
* More services from the same repository, such as a background worker or a [cron job](https://getfloo.com/docs/guides/cron-jobs.md).

Declare services, managed Postgres, sign-in, and domains in `floo.app.toml`. Store secrets outside git.

## 1. Add a Dockerfile

The application is `app.py` with an `app` instance, and its dependencies are in `requirements.txt`:

```text requirements.txt theme={null}
flask>=3.1
gunicorn>=23
psycopg[binary]>=3.2
```

```dockerfile Dockerfile theme={null}
FROM python:3.13-slim

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

WORKDIR /app

COPY requirements.txt ./
RUN pip install -r requirements.txt

COPY . .

CMD gunicorn --bind 0.0.0.0:$PORT --workers 2 app:app
```

To add a system package, install it before `COPY requirements.txt`, so the layer is cached across pushes:

```dockerfile theme={null}
RUN apt-get update -qq && \
    apt-get install -y --no-install-recommends ffmpeg && \
    rm -rf /var/lib/apt/lists/*
```

> [!TIP]
>
> 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 of `CMD`, without brackets, expands `$PORT`. Do not ship `flask run`: it is the development server.

## 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](https://getfloo.com/agents.md).

```bash theme={null}
floo init my-flask-app
```

For a single-service Flask app:

```toml floo.app.toml theme={null}
[app]
name = "my-flask-app"

[services.web]
type = "web"
path = "."
port = 8000
ingress = "public"
dev_command = "flask --app app run --debug --port 8000"
```

After adding Postgres, set `migrate_command = "flask --app app db upgrade"` under `[services.web]` if you use Flask-Migrate. Include the `migrations/` folder 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](https://getfloo.com/docs/guides/postgres.md#schema-portability-across-dev-and-prod) to keep the schema compatible with both old and new code.

## 3. Connect the repo and deploy

floo builds from your GitHub repository, not local files, so commit first. `floo deploy` pushes the commit and waits until the dev URL is live. The first time, it stops with one link if the floo GitHub App can't read the repository yet: a human opens it and installs the App on the account that owns the repository, then you run `floo deploy` again. See [Give floo access to your GitHub repository](https://getfloo.com/docs/introduction.md#2-give-floo-access-to-your-github-repository).

```bash theme={null}
git add . && git commit -m "feat: floo config + Dockerfile"
floo deploy --preflight
floo deploy
```

No GitHub repository? `floo deploy --hosted` has floo host the repository. See [Deploy without GitHub](https://getfloo.com/docs/deploy/without-github.md).

When it's done:

```bash theme={null}
floo apps show my-flask-app
```

> [!TIP]
>
> **Your Flask app is live** at `https://my-flask-app.getfloo.app`.
>
> Every `git push origin main` ships to dev.

## 4. Add a Postgres database

```toml floo.app.toml theme={null}
[managed.default]
type = "postgres"
```

```bash theme={null}
git add floo.app.toml && git commit -m "feat: add postgres"
floo deploy --preflight
floo deploy
```

Preflight warns `MANAGED_CREDS_TO_WEB` because the web service receives the database credentials. That is expected when the web service queries the database.

`DATABASE_URL` is injected into the runtime. psycopg 3 reads it as is, TLS settings included. Open one connection per request and close it when the request ends:

```python db.py theme={null}
import os

import psycopg
from flask import g


def get_db() -> psycopg.Connection:
    if "db" not in g:
        g.db = psycopg.connect(os.environ["DATABASE_URL"])
    return g.db


def close_db(exc: BaseException | None = None) -> None:
    db = g.pop("db", None)
    if db is not None:
        db.close()
```

```python app.py theme={null}
from flask import Flask

from db import close_db, get_db

app = Flask(__name__)
app.teardown_appcontext(close_db)


@app.get("/")
def index():
    with get_db().cursor() as cur:
        cur.execute("select now()")
        (now,) = cur.fetchone()
    return {"db_time": now.isoformat()}
```

For connection pooling, use `psycopg_pool.ConnectionPool` or Flask-SQLAlchemy with `postgresql+psycopg://`. Dev and prod each get a separate Postgres database and credentials, with no shared state.

## 5. Add per-user auth

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

```toml floo.app.toml theme={null}
[app]
name = "my-flask-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 Flask app.

Views read the headers, with no auth code, callback handlers, or session storage:

```python app.py theme={null}
from flask import abort, request


@app.get("/me")
def me():
    email = request.headers.get("X-Floo-User-Email")
    if not email:
        abort(401)
    return {
        "email": email,
        "id": request.headers.get("X-Floo-User-Id"),
        "name": request.headers.get("X-Floo-User-Name"),
    }
```

Locally, run `floo dev --fixture-user` (see [section 7](#7-local-development-with-dev-credentials)) or send the headers yourself with `curl -H 'X-Floo-User-Email: you@example.com' ...`. Access modes and identity headers in full: [App sign-in](https://getfloo.com/docs/guides/app-auth.md).

## 6. Add a custom domain

Declare the domain in `floo.app.toml`:

```toml theme={null}
[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:

Replace `owner/repo` with your GitHub repository. For a floo-hosted project, see [Environments](https://getfloo.com/docs/guides/environments.md#the-flow).

```bash theme={null}
gh release create v1 --repo owner/repo
```

Wait for the prod deploy to finish, then read the DNS records:

```bash theme={null}
floo domains show app.example.com --app my-flask-app
```

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

```bash theme={null}
floo domains watch app.example.com --app my-flask-app
```

With `ProxyFix` from [Common gotchas](#common-gotchas), Flask reads the host from `X-Forwarded-Host`. DNS setup and troubleshooting: [Custom domains](https://getfloo.com/docs/guides/custom-domains.md).

## 7. Local development with dev credentials

Install the dependencies in a virtualenv first:

```bash theme={null}
python3 -m venv .venv && . .venv/bin/activate && pip install -r requirements.txt
```

```bash theme={null}
floo dev --app my-flask-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.

The database exists after the first deploy that declares `[managed.default]`. Before that deploy, `floo dev` starts without `DATABASE_URL`.

To test signed-in flows, add `--fixture-user`:

```bash theme={null}
floo dev --app my-flask-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`.

* **Wrap the app in `ProxyFix`.** floo's edge terminates TLS and forwards `X-Forwarded-Proto: https`. Without `ProxyFix`, `url_for(..., _external=True)` builds `http://` links and secure cookies misbehave:

  ```python theme={null}
  from werkzeug.middleware.proxy_fix import ProxyFix

  app.wsgi_app = ProxyFix(app.wsgi_app, x_for=1, x_proto=1, x_host=1)
  ```

* **Set `SECRET_KEY` from the environment** if you use Flask sessions or flash messages: `floo env set SECRET_KEY --stdin --secret --app my-flask-app`, then `app.secret_key = os.environ["SECRET_KEY"]`.

* **A `.dockerignore` listing `.venv` and `__pycache__`.** `COPY . .` otherwise copies your local virtualenv into the image.

## Next steps

> [card] [App sign-in](https://getfloo.com/docs/guides/app-auth.md)
>
> Identity headers, access policies, and access modes in detail.

> [card] [Cron jobs](https://getfloo.com/docs/guides/cron-jobs.md)
>
> Run a Flask CLI command on a schedule in the same image.

> [card] [Dockerfiles](https://getfloo.com/docs/guides/dockerfiles.md)
>
> Layer order for fast pushes and recommended multi-stage builds.

> [card] [Production environments](https://getfloo.com/docs/guides/environments.md)
>
> Dev vs prod, promotion, env overrides.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.