FastAPI Forge

FastAPI Forge is a zero-runtime-dependency CLI that generates production-oriented FastAPI projects with PostgreSQL, Alembic migrations, JWT authentication, audit logging, and optional role-based access control (RBAC).

Generated features

• Access and rotating refresh tokens, revocation, and session management
• Password reset and email verification flows
• PostgreSQL with sync and async SQLAlchemy sessions
• Alembic migrations and an idempotent first-user seed command
• Structured logs, request IDs, rate limiting, CORS, trusted hosts, and security headers
• Liveness, readiness, and database health endpoints
• A multi-stage, non-root Docker image and local Compose stack
• Pytest tests, Ruff checks, and GitHub Actions CI

The RBAC variant adds hierarchical roles, permissions, per-user permissions, protected administration APIs, and RBAC seed data. The non-RBAC variant uses is_superuser for administrative authorization.

Requirements

• Python 3.9+ for the generator
• Python 3.12+ and PostgreSQL 14+ for generated applications
• Docker with Compose v2 for the optional container workflow

Install

Install the CLI in an isolated environment from a published package:

pipx install fastapi-forge-cli

Or install it into the current Python environment:

python -m pip install fastapi-forge-cli

The PyPI distribution is named fastapi-forge-cli because fastapi-forge is already used by another project. The installed terminal command remains fastapi-forge, and the Python import remains fastapi_forge.

For development from a source checkout:

cd fastapi-forge
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -e .

For generator development, run pip install -e ".[dev]". On Windows PowerShell, activate with .venv\\Scripts\\Activate.ps1.

Generate a project

# With RBAC
fastapi-forge create "Inventory API" --with-rbac

# Without RBAC
fastapi-forge create "Inventory API" --without-rbac

# Select a parent directory
fastapi-forge create "Inventory API" --with-rbac --output-dir ./projects

The same generator is available as a Python library:

from pathlib import Path

from fastapi_forge import create_project

project = create_project(
    name="Inventory API",
    output_dir=Path("./projects"),
    with_rbac=True,
)
print(project)

Generation is staged before installation at the destination. Existing projects are preserved unless --force is explicitly supplied, and symbolic-link destinations are never replaced.

If neither RBAC option is supplied, an interactive terminal asks which variant to use. Non-interactive environments default to RBAC. Existing destinations are protected; --force permanently replaces the matching generated-project directory.

usage: fastapi-forge create [-h] [--output-dir OUTPUT_DIR]
                            [--with-rbac | --without-rbac] [--force]
                            name

Getting help

Discover available commands:

fastapi-forge --help

See every project-generation option:

fastapi-forge create --help

Print copy-ready examples:

fastapi-forge examples

Common commands include:

fastapi-forge create "Inventory API" --with-rbac
fastapi-forge create "Public API" --without-rbac
fastapi-forge create "Billing API" --with-rbac --output-dir ./projects

Run a generated project

Python

Create the PostgreSQL database described by sample.env, then:

cd inventory-api
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements-dev.txt
cp sample.env .env
alembic upgrade head
python scripts/seed_first_user.py \
  --email admin@example.com \
  --password 'ChangeMe123!' \
  --full-name 'System Administrator'
uvicorn app.main:app --reload

Open http://localhost:8000/docs. Run pytest and ruff check . before committing.

Docker

cd inventory-api
cp sample.env .env
docker compose up --build

In another terminal:

docker compose exec api python scripts/seed_first_user.py \
  --email admin@example.com \
  --password 'ChangeMe123!' \
  --full-name 'System Administrator'

The Compose file is for local development; it uses development credentials and a bind mount.

Production deployment checklist

1. Set APP_ENV=production.
2. Supply a unique SECRET_KEY of at least 32 characters from a secret manager.
3. Set explicit ALLOWED_HOSTS and HTTPS ALLOWED_ORIGINS values.
4. Use managed PostgreSQL credentials and PG_SSLMODE=require, verify-ca, or verify-full.
5. Configure Redis when rate limits must be shared across replicas.
6. Configure SMTP and FRONTEND_URL for account emails.
7. Run alembic upgrade head as one release job before starting new replicas.
8. Terminate TLS at a trusted load balancer or reverse proxy.
9. Send stdout/stderr to centralized logging. Enable file logs only with persistent storage.
10. Monitor /api/v1/health/live and /api/v1/health/ready.
11. Back up PostgreSQL, test restores, rotate secrets, and define rollback procedures.

Production mode refuses startup with a default/short secret, wildcard hosts or origins, or a non-TLS database mode. Interactive API documentation is disabled.

docker build -t inventory-api:1.0.0 .
docker run --rm --env-file .env inventory-api:1.0.0 alembic upgrade head
docker run --rm --env-file .env -p 8000:8000 inventory-api:1.0.0

Do not run migrations independently from every application replica.

Generator development and release

pytest
python -m build
python -m twine check dist/*

Review generated output from both variants whenever templates change.

License

MIT