Bluefox Stack

One command
to a running app

Scaffold a complete FastAPI project with Postgres, Redis, auth, Alembic migrations, Docker, and tests. Run bfx dev and start building.

Quick start
01

Install the CLI

$ uv tool install bluefox-cli
# provides: bluefox (or bfx for short)
02

Create a project

$ bluefox init myapp
03

Generate migrations and start developing

$ cd myapp
$ bfx db migrate initial
# spins up Postgres, generates migration, stops Postgres
$ bfx dev
# Postgres + Redis start, migrations run, app reloads on changes
What you get

A complete project structure with everything wired together. Every file is ready to use — no boilerplate to fill in.

myapp/
  main.py app factory with welcome=True
  models.py root-level models (auto-discovered)
  items/ example module (auto-discovered)
    api.py router → mounted at /items
    models.py Item model
  .env dev defaults filled in
  .env.example all BluefoxSettings vars
  Makefile dev, test, migrate, run
  Dockerfile multi-stage uv build
  docker-compose.yml production on dokploy-network
  docker-compose.dev.yml local Postgres + Redis + hot reload
  alembic.ini
  migrations/
    env.py one-line Alembic config
    versions/
  tests/
    conftest.py bluefox-test fixtures
    test_health.py smoke test
    test_items.py auth-protected endpoint tests
  pyproject.toml deps managed by uv
Everything is wired

Zero-config dev

bfx dev starts Postgres + Redis via Docker Compose, runs Alembic migrations, and launches the app with --reload. Nothing to install manually.

Production Docker

Multi-stage Dockerfile with uv. Production compose uses dokploy-network, dev overrides with a local bridge. Same pattern, two environments.

Migrations ready

Alembic configured with configure_alembic() from bluefox-core. Run bfx db migrate add_users to generate — it spins up Postgres, auto-detects model changes, and stops.

Tests included

Health check, public endpoints, and auth-protected routes tested out of the box. Real Postgres via testcontainers, SAVEPOINT isolation. Run make test.

Auto-discovery

bluefox-core finds your */api.py routers and */models.py models automatically. Create a module directory and start coding — no registration needed.

No templating engine

Templates are plain Python strings. No Jinja, no cookiecutter. Easy to read, easy to maintain, zero extra dependencies.

Auth included

bluefox-auth wired out of the box — JWT tokens, cookie sessions, user registration, login, and Redis-backed token storage. The welcome page has a working sign-up form.

Just init

One command: bluefox init myapp. No interactive prompts, no plugin system, no config files. Opinionated and complete.

Generated code

The app factory and models are minimal — just enough to start. Add your routes, models, and business logic on top.

main.py 
from bluefox_auth import BluefoxAuth
from bluefox_components import setup_components
from bluefox_core import BluefoxSettings, create_bluefox_app


def create_app() -> object:
    settings = BluefoxSettings()
    app = create_bluefox_app(settings, welcome=True)
    BluefoxAuth(app, settings)
    setup_components(app)
    return app


app = create_app()
items/api.py 
from fastapi import APIRouter, Depends
from bluefox_auth import BluefoxUser, current_active_user

router = APIRouter()


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


@router.get("/me")
async def my_items(user: BluefoxUser = Depends(current_active_user)):
    return {"items": [], "owner": user.email}
# auto-mounted at /items — no registration needed
tests/conftest.py 
from bluefox_test import bluefox_test_setup
from bluefox_core import BluefoxBase

globals().update(bluefox_test_setup(base=BluefoxBase, app_factory="main:create_app"))
migrations/env.py 
from alembic import context
from bluefox_core.migrations import configure_alembic

configure_alembic(context)