Build a Django app on floo

This guide walks a Django 4+ 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 Django 4+ project (or a fresh django-admin startproject mysite).
The project pushed to a GitHub repository.
The floo CLI installed and authenticated (curl -fsSL https://getfloo.com/install.sh | bash then floo auth login).

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

COPY . .

RUN python manage.py collectstatic --noinput

EXPOSE 8000
CMD ["gunicorn", "mysite.wsgi:application", "--bind", "0.0.0.0:8000", "--workers", "3"]

Add gunicorn and dj-database-url to your requirements.txt:

Django>=4.2
gunicorn>=21
dj-database-url>=2.1
psycopg[binary]>=3
whitenoise>=6.6
requests>=2.31

Bind to 0.0.0.0, not 127.0.0.1. Cloud Run only routes traffic to processes bound to all interfaces.

2. Configure Django for production

Update mysite/settings.py to read floo’s runtime env vars:

mysite/settings.py

import os
from pathlib import Path
import dj_database_url

BASE_DIR = Path(__file__).resolve().parent.parent

SECRET_KEY = os.environ.get("DJANGO_SECRET_KEY", "dev-only-do-not-use-in-prod")
DEBUG = os.environ.get("DJANGO_DEBUG", "false").lower() == "true"

# floo's edge sets X-Forwarded-Host. Trust it for ALLOWED_HOSTS.
ALLOWED_HOSTS = ["*"] if DEBUG else [
    ".on.getfloo.com",
    *os.environ.get("DJANGO_ALLOWED_HOSTS", "").split(","),
]

# Trust X-Forwarded-Proto so Django knows the request is HTTPS behind floo's edge.
SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")
USE_X_FORWARDED_HOST = True

# Cookies
SESSION_COOKIE_SECURE = not DEBUG
SESSION_COOKIE_HTTPONLY = True
SESSION_COOKIE_SAMESITE = "Lax"
CSRF_COOKIE_SECURE = not DEBUG

# WhiteNoise serves collectstatic output
MIDDLEWARE = [
    "django.middleware.security.SecurityMiddleware",
    "whitenoise.middleware.WhiteNoiseMiddleware",
    # ... rest of your middleware
]

STATIC_ROOT = BASE_DIR / "staticfiles"
STORAGES = {
    "default": {"BACKEND": "django.core.files.storage.FileSystemStorage"},
    "staticfiles": {"BACKEND": "whitenoise.storage.CompressedManifestStaticFilesStorage"},
}

# Database — read DATABASE_URL from floo
DATABASES = {
    "default": dj_database_url.config(default="sqlite:///db.sqlite3", conn_max_age=600),
}

Generate a real DJANGO_SECRET_KEY and set it once the app exists (step 4).

3. Initialize the floo config

floo init my-django-app

floo.app.toml

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

[services.web]
type = "web"
path = "."
port = 8000
ingress = "public"
dev_command = "python manage.py runserver 0.0.0.0:8000"
migrate_command = "python manage.py migrate --noinput"

migrate_command runs after every deploy and promote.

4. Connect the repo and deploy

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

Set the secret key once the app exists, then redeploy:

python -c 'from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())' | floo env set DJANGO_SECRET_KEY --stdin --secret --app my-django-app
floo redeploy --app my-django-app

floo apps show my-django-app

Your Django app is live at https://my-django-app-dev.on.getfloo.com.

5. 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. dj-database-url parses it automatically — no settings change needed. The next deploy runs your migrate_command against the new database before traffic shifts.

6. Add per-user auth

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

floo.app.toml

[app]
name = "my-django-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 Django app.

Add a tiny middleware that hangs the floo user on request.floo_user:

mysite/middleware.py

from dataclasses import dataclass

@dataclass
class FlooUser:
    id: str
    email: str
    name: str | None

class FlooUserMiddleware:
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        email = request.META.get("HTTP_X_FLOO_USER_EMAIL")
        user_id = request.META.get("HTTP_X_FLOO_USER_ID")
        name = request.META.get("HTTP_X_FLOO_USER_NAME")
        request.floo_user = FlooUser(id=user_id, email=email, name=name) if email else None
        return self.get_response(request)

Wire it up:

mysite/settings.py

MIDDLEWARE = [
    # ... existing entries
    "mysite.middleware.FlooUserMiddleware",
]

Use it in views:

mysite/views.py

from django.http import JsonResponse, HttpResponseUnauthorized

def dashboard(request):
    if not request.floo_user:
        return HttpResponseUnauthorized()
    return JsonResponse({"hello": request.floo_user.email})

For local development, send the headers yourself or extend the middleware to inject a fixture user when they’re missing. For the full reference on access modes and identity headers, see Add User Auth to Your App.

7. Add a custom domain

floo domains add app.example.com --app my-django-app
floo env set DJANGO_ALLOWED_HOSTS=app.example.com --app my-django-app
floo redeploy --app my-django-app

Add the traffic and _floo-verify TXT records shown by floo domains add, then run floo domains verify app.example.com --app my-django-app. USE_X_FORWARDED_HOST = True and SECURE_PROXY_SSL_HEADER mean Django builds correct absolute URLs (for redirects, mailers, request.build_absolute_uri) without extra config.

8. Local development with prod data

floo dev --app my-django-app

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-django-app --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.
DEBUG = True in prod is a security hole. Set DJANGO_DEBUG=false (or just don’t set it — the default in the example above).
DJANGO_SECRET_KEY must be set. Without it, Django’s session cookies can be forged. Generate with get_random_secret_key() and set via floo env set.
collectstatic runs in the Dockerfile. WhiteNoise’s CompressedManifestStaticFilesStorage requires it.
SECURE_PROXY_SSL_HEADER is required behind a proxy. Without it, request.is_secure() returns False and Django redirect loops can form when SECURE_SSL_REDIRECT=True.

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.

Custom Domains

DNS, verification, multi-service routing.

Cron Jobs

Schedule recurring Django management commands inside your container.

Get Started

Build with...

Build your app

Environments

Managed Services

Observe

Access

For Agents

Build a Django app on floo

Before you start

1. Add a Dockerfile

2. Configure Django for production

3. Initialize the floo config

4. Connect the repo and deploy

5. Add a Postgres database

6. Add per-user auth

7. Add a custom domain

8. Local development with prod data

Common gotchas

What’s next

Add User Auth — full reference

Managed Services

Custom Domains

Cron Jobs

​Before you start

​1. Add a Dockerfile

​2. Configure Django for production

​3. Initialize the floo config

​4. Connect the repo and deploy

​5. Add a Postgres database

​6. Add per-user auth

​7. Add a custom domain

​8. Local development with prod data

​Common gotchas

​What’s next

Add User Auth — full reference

Managed Services

Custom Domains

Cron Jobs

Before you start

1. Add a Dockerfile

2. Configure Django for production

3. Initialize the floo config

4. Connect the repo and deploy

5. Add a Postgres database

6. Add per-user auth

7. Add a custom domain

8. Local development with prod data

Common gotchas

What’s next