Getting started¶

Prerequisites¶

uv installed
Docker running (for make dev)

Install the CLI¶

uv tool install bluefox-cli

This installs two commands: bluefox and bfx (a shorter alias).

Create a project¶

bluefox init myapp

This will:

Create the myapp/ directory with all project files
Run uv init to set up the Python project
Run uv add bluefox-core alembic asyncpg for runtime dependencies
Run uv add --dev bluefox-test pytest for test dependencies

Start developing¶

cd myapp
make dev

Docker Compose starts a local Postgres container, runs Alembic migrations, and launches the FastAPI app with --reload. Visit http://localhost:8000 to see the interactive welcome page with system status and a message playground.

Project structure¶

myapp/
  main.py                     # App factory (welcome=True)
  models.py                   # Root-level models (auto-discovered)
  items/                      # Example module (auto-discovered)
    __init__.py
    api.py                    # Router → auto-mounted at /items
    models.py                 # Item model → auto-discovered
  .env                        # Dev environment variables
  .env.example                # Template for production
  Makefile                    # Dev workflow commands
  Dockerfile                  # Multi-stage production build
  docker-compose.yml          # Production compose
  docker-compose.dev.yml      # Dev compose (local Postgres)
  alembic.ini                 # Migration config
  migrations/
    env.py                    # One-line Alembic setup
    versions/                 # Migration files
  tests/
    conftest.py               # Test fixtures
    test_health.py            # Smoke test
  pyproject.toml              # Dependencies

Auto-discovery¶

bluefox-core automatically discovers your code by convention:

Models: any models.py or */models.py file is imported, registering tables in BluefoxBase.metadata
Routers: any api.py or */api.py file with a router = APIRouter() is mounted at /{dirname}

No manual imports or registration needed. Just create a module directory, add api.py and/or models.py, and it works.

Create your first migration¶

The generated project includes an Item model in items/models.py. To create a migration for it:

make migrate-make name=initial

This generates a migration file in migrations/versions/. The next time you run make dev, it will be applied automatically.

Run tests¶

make test

Tests use bluefox-test with real Postgres via testcontainers. Each test runs inside a SAVEPOINT — no cleanup needed.

Next steps¶

Add a new module: create users/api.py with a router and users/models.py — they're auto-discovered
See Generated files for details on each file
See Deployment for deploying with Dokploy