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:

• A welcome page at /
• Health check at /health
• Auto-generated API docs at /docs and /redoc

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¶

from fastapi import APIRouter

router = APIRouter()

@router.get("/hello")
async def hello():
    return {"message": "Hello, world!"}

app.include_router(router, prefix="/api")

When you register a GET / route, it automatically replaces the built-in welcome page.

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¶