Bluefox Stack

One command
to a running app

Scaffold a complete FastAPI project with Postgres, Alembic migrations, Docker, and tests. Run make 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

Start developing

$ cd myapp
$ make dev
# Postgres starts, 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 + hot reload
  alembic.ini
  migrations/
    env.py one-line Alembic config
    versions/
  tests/
    conftest.py bluefox-test fixtures
    test_health.py smoke test
  pyproject.toml deps managed by uv
Everything is wired

Zero-config dev

make dev starts Postgres 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 make migrate-make name=add_users to generate, make migrate to apply.

Tests included

conftest.py wired with bluefox-test fixtures. Real Postgres via testcontainers, async client, 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.

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_core import BluefoxSettings, create_bluefox_app


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


app = create_app()
items/api.py 
from fastapi import APIRouter

router = APIRouter()


@router.get("/")
async def list_items():
    return {"items": []}
# 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)