Quick start

This tutorial walks through a complete obox-builder setup: scaffold a project, mount the admin, create the database and log in. It takes a few minutes.

Requirements

• Python 3.11 or later
• uv
• Git

1. Install obox-builder

!!! note "Pre-release" obox-builder 0.1 is not published on PyPI yet, so install it from the repository. Once released, uv add obox-builder will be enough.

Clone the repository and install its dependencies:

git clone https://github.com/vinhgiga/obox-builder
cd obox-builder
uv sync --all-extras

2. Create a project

From the repository root, run the startproject command:

uv run obox startproject demo ../demo
cd ../demo

The command generates a Django-style project skeleton:

demo/
├── manage.py           # CLI entry point
├── pyproject.toml      # project metadata and dependencies
├── .env.example        # OBOX_-prefixed environment overrides
├── config/
│   ├── settings.py     # your Settings class
│   ├── urls.py         # ROOT_URLCONF (a list of routers)
│   └── asgi.py         # ASGI application
├── apps/               # your apps live here
├── migrations/         # Alembic migrations
├── static/
└── templates/

3. Point the project at obox-builder

Open pyproject.toml and uncomment the [tool.uv.sources] block at the bottom, so uv resolves obox-builder from your local checkout:

[tool.uv.sources]
obox-builder = { path = "../obox-builder", editable = true }

Then create the project environment:

uv sync

4. Mount the admin

config/urls.py ships with a routers list. Add the admin router to it:

from fastapi import APIRouter

from obox_builder.contrib.admin.site import site as admin_site

router = APIRouter()


@router.get("/")
def index() -> dict[str, str]:
    return {"message": "Hello from demo"}


routers = [router, (admin_site.get_router(), "/admin")]

config/settings.py already installs obox_builder.contrib.auth and obox_builder.contrib.admin, and points DATABASE_URL at a local SQLite file, so the admin works out of the box.

5. Create the database

uv run manage.py makemigrations
uv run manage.py migrate

makemigrations generates a migration for the built-in auth models (users, roles, permissions, sessions). migrate applies it and syncs the default permissions.

6. Create a superuser

uv run manage.py createsuperuser

You will be prompted for a username, an email address and a password.

7. Run the development server

uv run manage.py runserver --reload

Now open:

• http://127.0.0.1:8000/ — the project's root view.
• http://127.0.0.1:8000/admin — the admin UI. Log in with the superuser you just created to reach the dashboard, where you can manage users, roles and the permission matrix.

!!! tip "Configuration" Settings are pydantic-settings models: every field can be overridden with an OBOX_-prefixed environment variable or through a .env file (OBOX_DATABASE_URL, OBOX_SECRET_KEY, OBOX_DEBUG, ...). See .env.example in the scaffold. To use PostgreSQL, install the obox-builder[postgres] extra and set a postgresql+psycopg_async:// (or postgresql+asyncpg://) DATABASE_URL.

Next steps

Your first app. Scaffold an app, register it in INSTALLED_APPS and define models with the SQLAlchemy helpers:

uv run manage.py startapp blog apps/blog

# apps/blog/models.py
import sqlalchemy as sa
from obox_builder.db import Model, TimestampMixin
from sqlalchemy.orm import Mapped, mapped_column


class Post(Model, TimestampMixin):
    id: Mapped[int] = mapped_column(primary_key=True)
    title: Mapped[str] = mapped_column(sa.String(200))
    body: Mapped[str] = mapped_column(sa.Text, default="")

Add "apps.blog" to INSTALLED_APPS, then run makemigrations and migrate again. The app's CRUD permissions (blog.view_post, ...) are synced automatically after the migration.

Explore the CLI. uv run manage.py --help lists every command, including check, shell, showurls and collectstatic.

Write tests. The testing guide covers the pytest plugin, db/client/login fixtures and the user/role factories.