Skip to content

Getting started

Prerequisites

  • uv installed
  • Docker running (for bfx 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
# or, to scaffold in the current directory:
bluefox init .

This will:

  1. Create the myapp/ directory with all project files
  2. Run uv init to set up the Python project
  3. Run uv add bluefox-core>=0.4.0 bluefox-auth>=0.9.0 bluefox-components alembic asyncpg for runtime dependencies
  4. Run uv add --dev bluefox-test pytest for test dependencies

Generate the initial migration

The generated project includes models from both bluefox-auth (users, sessions) and the example items/ module. Generate a migration before starting the app:

cd myapp
bfx db migrate initial

This spins up a temporary Postgres container, runs Alembic autogenerate to detect all model tables, and stops the container. The migration file is written to migrations/versions/.

Start developing

bfx dev

Docker Compose starts Postgres, Redis, runs Alembic migrations, and launches the FastAPI app with --reload. Visit http://localhost:8000 to see the interactive welcome page with system status, a message playground, and an auth panel where you can register and log in.

Project structure

myapp/
  main.py                     # App factory with auth (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 (Postgres + Redis)
  alembic.ini                 # Migration config
  migrations/
    env.py                    # One-line Alembic setup
    script.py.mako            # Migration file template
    versions/                 # Migration files
  tests/
    conftest.py               # Test fixtures
    test_health.py            # Smoke test
    test_items.py             # Auth-protected endpoint tests
  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.

Authentication

The generated app includes bluefox-auth out of the box. The welcome page has a built-in auth panel where you can register users and log in. Auth endpoints are available at:

  • POST /auth/register — create a new user
  • POST /auth/login — log in (returns JWT + sets cookie)
  • POST /auth/logout — log out
  • GET /auth/me — get current user

Run tests

uv run pytest

Tests use bluefox-test with real Postgres via testcontainers. Each test runs inside a SAVEPOINT — no cleanup needed. You can also use make test as a shortcut.

The generated test_items.py includes three tests out of the box:

  • Public endpoint — GET /items/ returns 200
  • Auth required — GET /items/me returns 401 without a token
  • Authenticated flow — registers a user, logs in, and accesses the protected endpoint with a Bearer token

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 CLI commands for all available commands
  • See Deployment for deploying with Bluefox Cloud