First Run Guide¶

Congratulations on setting up the FastAPI Boilerplate! This guide will walk you through testing your installation, understanding the basics, and making your first customizations.

Verification Checklist¶

Before diving deeper, let's verify everything is working correctly.

1. Check All Services¶

Ensure all services are running:

# For Docker Compose users
docker compose ps

# Expected output:
# NAME                          COMMAND                  SERVICE   STATUS
# fastapi-boilerplate-web-1     "uvicorn app.main:app…"  web       running
# fastapi-boilerplate-db-1      "docker-entrypoint.s…"  db        running
# fastapi-boilerplate-redis-1   "docker-entrypoint.s…"  redis     running
# fastapi-boilerplate-worker-1  "arq src.app.core.wo…"  worker    running

2. Test API Endpoints¶

Visit these URLs to confirm your API is working:

API Documentation: - Swagger UI: http://localhost:8000/docs - ReDoc: http://localhost:8000/redoc

Health Check:

curl http://localhost:8000/api/v1/health

Expected response:

{
  "status": "healthy",
  "timestamp": "2024-01-01T12:00:00Z"
}

3. Database Connection¶

Check if the database tables were created:

# For Docker Compose
docker compose exec db psql -U postgres -d myapp -c "\dt"

# You should see tables like:
# public | users        | table | postgres
# public | posts        | table | postgres
# public | tiers        | table | postgres
# public | rate_limits  | table | postgres

4. Redis Connection¶

Test Redis connectivity:

# For Docker Compose
docker compose exec redis redis-cli ping

# Expected response: PONG

Initial Setup¶

Before testing features, you need to create the first superuser and tier.

Creating the First Superuser¶

Prerequisites

Make sure the database and tables are created before running create_superuser. The database should be running and the API should have started at least once.

Using Docker Compose¶

If using Docker Compose, uncomment this section in your docker-compose.yml:

#-------- uncomment to create first superuser --------
create_superuser:
  build:
    context: .
    dockerfile: Dockerfile
  env_file:
    - ./src/.env
  depends_on:
    - db
  command: python -m src.scripts.create_first_superuser
  volumes:
    - ./src:/code/src

Then run:

# Start services and run create_superuser automatically
docker compose up -d

# Or run it manually
docker compose run --rm create_superuser

# Stop the create_superuser service when done
docker compose stop create_superuser

From Scratch¶

If running manually, use:

# Make sure you're in the root folder
uv run python -m src.scripts.create_first_superuser

Creating the First Tier¶

Prerequisites

Make sure the database and tables are created before running create_tier.

Using Docker Compose¶

Uncomment the create_tier service in docker-compose.yml and run:

docker compose run --rm create_tier

From Scratch¶

# Make sure you're in the root folder
uv run python -m src.scripts.create_first_tier

Testing Core Features¶

Let's test the main features of your API.

Authentication Flow¶

Use the admin credentials you set in your .env file:

curl -X POST "http://localhost:8000/api/v1/login" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin&password=your_admin_password"

You should receive a response like:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "token_type": "bearer",
  "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}

2. Create a New User¶

curl -X POST "http://localhost:8000/api/v1/users" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "username": "johndoe", 
    "email": "john@example.com",
    "password": "securepassword123"
  }'

3. Test Protected Endpoint¶

Use the access token from step 1:

curl -X GET "http://localhost:8000/api/v1/users/me" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN_HERE"

CRUD Operations¶

1. Create a Post¶

curl -X POST "http://localhost:8000/api/v1/posts" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN_HERE" \
  -d '{
    "title": "My First Post",
    "content": "This is the content of my first post!"
  }'

2. Get All Posts¶

curl -X GET "http://localhost:8000/api/v1/posts" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN_HERE"

3. Get Posts with Pagination¶

curl -X GET "http://localhost:8000/api/v1/posts?page=1&items_per_page=5" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN_HERE"

Background Tasks¶

Test the job queue system:

1. Submit a Background Task¶

curl -X POST "http://localhost:8000/api/v1/tasks/task?message=hello" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN_HERE"

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

2. Check Task Status¶

curl -X GET "http://localhost:8000/api/v1/tasks/task/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN_HERE"

Caching¶

Test the caching system:

1. Make a Cached Request¶

# First request (cache miss)
curl -X GET "http://localhost:8000/api/v1/users/johndoe" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN_HERE" \
  -w "Time: %{time_total}s\n"

# Second request (cache hit - should be faster)
curl -X GET "http://localhost:8000/api/v1/users/johndoe" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN_HERE" \
  -w "Time: %{time_total}s\n"

Your First Customization¶

Let's create a simple custom endpoint to see how easy it is to extend the boilerplate.

1. Create a Simple Model¶

Create src/app/models/item.py:

from sqlalchemy import String
from sqlalchemy.orm import Mapped, mapped_column

from app.core.db.database import Base


class Item(Base):
    __tablename__ = "items"

    id: Mapped[int] = mapped_column("id", autoincrement=True, nullable=False, unique=True, primary_key=True, init=False)
    name: Mapped[str] = mapped_column(String(100))
    description: Mapped[str] = mapped_column(String(500), default="")

2. Create Pydantic Schemas¶

Create src/app/schemas/item.py:

from pydantic import BaseModel, Field


class ItemBase(BaseModel):
    name: str = Field(..., min_length=1, max_length=100)
    description: str = Field("", max_length=500)


class ItemCreate(ItemBase):
    pass


class ItemCreateInternal(ItemCreate):
    pass


class ItemRead(ItemBase):
    id: int


class ItemUpdate(BaseModel):
    name: str | None = None
    description: str | None = None


class ItemUpdateInternal(ItemUpdate):
    pass


class ItemDelete(BaseModel):
    is_deleted: bool = True

3. Create CRUD Operations¶

Create src/app/crud/crud_items.py:

from fastcrud import FastCRUD

from app.models.item import Item
from app.schemas.item import ItemCreateInternal, ItemUpdate, ItemUpdateInternal, ItemDelete

CRUDItem = FastCRUD[Item, ItemCreateInternal, ItemUpdate, ItemUpdateInternal, ItemDelete]
crud_items = CRUDItem(Item)

4. Create API Endpoints¶

Create src/app/api/v1/items.py:

from typing import Annotated

from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy.ext.asyncio import AsyncSession

from app.api.dependencies import get_current_user
from app.core.db.database import async_get_db
from app.crud.crud_items import crud_items
from app.schemas.item import ItemCreate, ItemRead, ItemUpdate
from app.schemas.user import UserRead

router = APIRouter(tags=["items"])


@router.post("/", response_model=ItemRead, status_code=201)
async def create_item(
    item: ItemCreate,
    db: Annotated[AsyncSession, Depends(async_get_db)],
    current_user: Annotated[UserRead, Depends(get_current_user)]
):
    """Create a new item."""
    db_item = await crud_items.create(db=db, object=item)
    return db_item


@router.get("/{item_id}", response_model=ItemRead)
async def get_item(
    item_id: int,
    db: Annotated[AsyncSession, Depends(async_get_db)]
):
    """Get an item by ID."""
    db_item = await crud_items.get(db=db, id=item_id)
    if not db_item:
        raise HTTPException(status_code=404, detail="Item not found")
    return db_item


@router.get("/", response_model=list[ItemRead])
async def get_items(
    db: Annotated[AsyncSession, Depends(async_get_db)],
    skip: int = 0,
    limit: int = 100
):
    """Get all items."""
    items = await crud_items.get_multi(db=db, offset=skip, limit=limit)
    return items["data"]


@router.patch("/{item_id}", response_model=ItemRead)
async def update_item(
    item_id: int,
    item_update: ItemUpdate,
    db: Annotated[AsyncSession, Depends(async_get_db)],
    current_user: Annotated[UserRead, Depends(get_current_user)]
):
    """Update an item."""
    db_item = await crud_items.get(db=db, id=item_id)
    if not db_item:
        raise HTTPException(status_code=404, detail="Item not found")

    updated_item = await crud_items.update(db=db, object=item_update, id=item_id)
    return updated_item


@router.delete("/{item_id}")
async def delete_item(
    item_id: int,
    db: Annotated[AsyncSession, Depends(async_get_db)],
    current_user: Annotated[UserRead, Depends(get_current_user)]
):
    """Delete an item."""
    db_item = await crud_items.get(db=db, id=item_id)
    if not db_item:
        raise HTTPException(status_code=404, detail="Item not found")

    await crud_items.delete(db=db, id=item_id)
    return {"message": "Item deleted successfully"}

5. Register the Router¶

Add your new router to src/app/api/v1/__init__.py:

from fastapi import APIRouter

from app.api.v1.login import router as login_router
from app.api.v1.logout import router as logout_router
from app.api.v1.posts import router as posts_router
from app.api.v1.rate_limits import router as rate_limits_router
from app.api.v1.tasks import router as tasks_router
from app.api.v1.tiers import router as tiers_router
from app.api.v1.users import router as users_router
from app.api.v1.items import router as items_router  # Add this line

router = APIRouter(prefix="/v1")
router.include_router(login_router, prefix="/login")
router.include_router(logout_router, prefix="/logout") 
router.include_router(users_router, prefix="/users")
router.include_router(posts_router, prefix="/posts")
router.include_router(tasks_router, prefix="/tasks")
router.include_router(tiers_router, prefix="/tiers")
router.include_router(rate_limits_router, prefix="/rate_limits")
router.include_router(items_router, prefix="/items")  # Add this line

6. Create and Run Migration¶

Import your new model in src/app/models/__init__.py:

from .user import User
from .post import Post
from .tier import Tier
from .rate_limit import RateLimit
from .item import Item  # Add this line

Create and run the migration:

# For Docker Compose
docker compose exec web alembic revision --autogenerate -m "Add items table"
docker compose exec web alembic upgrade head

# For manual installation
cd src
uv run alembic revision --autogenerate -m "Add items table"
uv run alembic upgrade head

7. Test Your New Endpoint¶

Restart your application and test the new endpoints:

# Create an item
curl -X POST "http://localhost:8000/api/v1/items/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN_HERE" \
  -d '{
    "name": "My First Item",
    "description": "This is a test item"
  }'

# Get all items
curl -X GET "http://localhost:8000/api/v1/items/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN_HERE"

Debugging Common Issues¶

Logs and Monitoring¶

Check Application Logs¶

# For Docker Compose
docker compose logs web

# For manual installation
tail -f src/app/logs/app.log

Check Database Logs¶

# For Docker Compose
docker compose logs db

Check Worker Logs¶

# For Docker Compose
docker compose logs worker

Performance Testing¶

Test API Response Times¶

# Test endpoint performance
curl -w "Time: %{time_total}s\n" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN_HERE" \
  http://localhost:8000/api/v1/users/me

Test Database Performance¶

# Check active connections
docker compose exec db psql -U postgres -d myapp -c "SELECT count(*) FROM pg_stat_activity;"

Monitoring Dashboard¶

Redis Monitor¶

# Monitor Redis operations
docker compose exec redis redis-cli monitor

Database Activity¶

# Check database activity
docker compose exec db psql -U postgres -d myapp -c "SELECT * FROM pg_stat_activity;"

Next Steps¶

Now that you've verified everything works and created your first custom endpoint, you're ready to dive deeper:

Essential Learning¶

Project Structure - Understand how the code is organized
Database Guide - Learn about models, schemas, and CRUD operations
Authentication - Deep dive into JWT and user management

Advanced Features¶

Caching - Speed up your API with Redis caching
Background Tasks - Process long-running tasks asynchronously
Rate Limiting - Protect your API from abuse

Development Workflow¶

Development Guide - Best practices for extending the boilerplate
Testing - Write tests for your new features
Production - Deploy your API to production

Getting Help¶

If you encounter any issues:

Check the logs for error messages
Verify your configuration in the .env file
Review the GitHub Issues for common solutions
Search existing issues on GitHub
Create a new issue with detailed information

Congratulations!¶

You've successfully:

Verified your FastAPI Boilerplate installation
Tested core API functionality
Created your first custom endpoint
Run database migrations
Tested authentication and CRUD operations

You're now ready to build amazing APIs with FastAPI!

First Run Guide¶

Verification Checklist¶

1. Check All Services¶

2. Test API Endpoints¶

3. Database Connection¶

4. Redis Connection¶

Initial Setup¶

Creating the First Superuser¶

Using Docker Compose¶

From Scratch¶

Creating the First Tier¶

Using Docker Compose¶

From Scratch¶

Testing Core Features¶

Authentication Flow¶

1. Login with Admin User¶

2. Create a New User¶

3. Test Protected Endpoint¶

CRUD Operations¶

1. Create a Post¶

2. Get All Posts¶

3. Get Posts with Pagination¶

Background Tasks¶

1. Submit a Background Task¶

2. Check Task Status¶

Caching¶

1. Make a Cached Request¶

Your First Customization¶

1. Create a Simple Model¶

2. Create Pydantic Schemas¶

3. Create CRUD Operations¶

4. Create API Endpoints¶

5. Register the Router¶

6. Create and Run Migration¶

7. Test Your New Endpoint¶

Debugging Common Issues¶

Logs and Monitoring¶

Check Application Logs¶

Check Database Logs¶

Check Worker Logs¶

Performance Testing¶

Test API Response Times¶

Test Database Performance¶

Monitoring Dashboard¶

Redis Monitor¶

Database Activity¶

Next Steps¶

Essential Learning¶

Advanced Features¶

Development Workflow¶

Getting Help¶

Congratulations!¶