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 BluefoxSettings
  models.py example model inheriting BluefoxBase
  .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.

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(MODELS_MODULE="models")
    return create_bluefox_app(settings)


app = create_app()
tests/conftest.py 
from bluefox_test import bluefox_test_setup
from models import Example  # noqa: F401 — register models
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)