Skip to content

Getting Started

Prerequisites

  • Python 3.12+
  • uv package manager (recommended) or pip
  • Docker and Docker Compose

Installation

uv tool install paxx

Create Your First Project

paxx bootstrap myproject

This creates a new directory myproject/ with the complete project structure.

Bootstrap Options

# With a description
paxx bootstrap myproject --description "My awesome API"

# With author name
paxx bootstrap myproject --author "Your Name"

# In a specific directory
paxx bootstrap myproject --output-dir /path/to/projects

# Bootstrap in current directory
paxx bootstrap .

# Skip confirmation prompts (CI-friendly)
paxx bootstrap myproject --force

Start the Development Environment

cd myproject
docker compose up

This starts both the application and PostgreSQL database. The app runs with hot-reload enabled.

Your API is now running at http://127.0.0.1:8000.

Create Your First Feature

Features are domain modules that contain your business logic. Create one with:

paxx feature create users

This generates:

features/users/
├── __init__.py
├── config.py      # Router prefix and tags
├── models.py      # SQLAlchemy models
├── schemas.py     # Pydantic schemas
├── services.py    # Business logic
└── routes.py      # API endpoints

Set Up the Database

After defining your models, create and apply migrations:

# Create a migration
paxx db migrate "add users table"

# Apply the migration
paxx db upgrade

Add Infrastructure (Optional)

Add infrastructure components as needed:

paxx infra list           # List all available components

paxx infra add redis      # Redis caching
paxx infra add storage    # Object storage (S3/local)

Add extensions (Optional)

Add extensions:

# Extensions (enhances existing infrastructure)
paxx ext list             # List all available extensions

paxx ext add arq          # Background tasks (requires redis)
paxx ext add websocket    # WebSocket support

Project Structure Overview

myproject/
├── main.py              # Application entry point
├── settings.py          # Configuration
├── docker-compose.yml   # Development environment
├── core/                # Shared utilities
├── db/                  # Database setup & migrations
├── features/            # Domain features
├── services/            # Global features
└── e2e/                 # End-to-end tests

See Project Structure for detailed documentation.

Next Steps