Getting started¶

Installation¶

uv add bluefox-core

Minimal app (no database)¶

Create main.py:

from bluefox_core import BluefoxSettings, create_bluefox_app

settings = BluefoxSettings()
app = create_bluefox_app(settings)

Run it:

uv run uvicorn main:app --reload

This gives you:

• Health check at /health
• Auto-generated API docs at /docs and /redoc
• Any */api.py routers in your project are mounted automatically

Configuration¶

Copy the example environment file and edit it:

cp .env.example .env

All settings have sensible defaults — the only one you'll need for database work is DATABASE_URL.

Adding a database¶

Set the DATABASE_URL environment variable (or add it to .env):

DATABASE_URL=postgresql://user:pass@localhost:5432/mydb

The app factory automatically creates an async SQLAlchemy engine and wires it into the lifespan. The /readiness endpoint will verify database connectivity.

Adding routes¶

Routes are auto-discovered by convention. Create a module with an api.py file:

# items/api.py
from fastapi import APIRouter

router = APIRouter()

@router.get("/")
async def list_items():
    return {"items": []}

This is automatically mounted at /items — the directory name becomes the URL prefix. No registration needed.

See the Auto-discovery guide for full details.

Welcome page¶

For new projects, enable the interactive welcome page:

app = create_bluefox_app(settings, welcome=True)

This gives you a landing page at / with system status badges, a message playground, and instructions for creating your first module. Remove welcome=True when you're ready to use your own root route.

Subclassing settings¶

Add your own configuration fields by subclassing BluefoxSettings:

from bluefox_core import BluefoxSettings

class MySettings(BluefoxSettings):
    STRIPE_API_KEY: str = ""
    MAX_UPLOAD_SIZE: int = 10_000_000

settings = MySettings()
# Reads STRIPE_API_KEY and MAX_UPLOAD_SIZE from env / .env file

Using the demo app¶

Pass demo=True to see a working Todo CRUD example:

app = create_bluefox_app(settings, demo=True)

This mounts endpoints at /demo/todos with full create, read, update, and delete operations. See the Demo app guide for details.

Database migrations¶

bluefox-core includes Alembic integration with automatic model discovery. Any models.py file in your project that uses BluefoxBase is picked up automatically — no configuration needed.

See the Migrations guide for the full setup.

Quick version:

uv run alembic init -t async migrations

Replace migrations/env.py with:

from alembic import context
from bluefox_core.migrations import configure_alembic

configure_alembic(context)

Then create and run migrations:

make migrate-make m="initial tables"
make migrate

Environment variables¶