Metadata-Version: 2.4
Name: fastapi-forge-cli
Version: 0.1.3
Summary: Generate production-oriented FastAPI projects with optional RBAC.
Author: FastAPI Forge Contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/Chintan-Trada/fastapi-forge-cli
Project-URL: Repository, https://github.com/Chintan-Trada/fastapi-forge-cli
Project-URL: Issues, https://github.com/Chintan-Trada/fastapi-forge-cli/issues
Keywords: fastapi,boilerplate,generator,rbac,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: build<2.0,>=1.2; extra == "dev"
Requires-Dist: pytest<9.0,>=8.0; extra == "dev"
Requires-Dist: ruff<1.0,>=0.8; extra == "dev"
Requires-Dist: twine<7.0,>=5.1; extra == "dev"
Dynamic: license-file

# FastAPI Forge

[![PyPI version](https://img.shields.io/pypi/v/fastapi-forge-cli.svg)](https://pypi.org/project/fastapi-forge-cli/)
[![Python versions](https://img.shields.io/pypi/pyversions/fastapi-forge-cli.svg)](https://pypi.org/project/fastapi-forge-cli/)
[![License](https://img.shields.io/pypi/l/fastapi-forge-cli.svg)](https://github.com/Chintan-Trada/fastapi-forge-cli/blob/main/LICENSE)

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

## Installation

Install or upgrade the CLI from PyPI:

```bash
python -m pip install --upgrade 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`.

## Quick start

Generate a production-oriented FastAPI project with RBAC:

```bash
fastapi-forge create "Inventory API" --with-rbac
cd inventory-api
```

Run `fastapi-forge --help` to see all commands and
`fastapi-forge create --help` to see every generation option.

## Development installation

For development from a source checkout:

```bash
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

```bash
# 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:

```python
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.

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

## Getting help

Discover available commands:

```bash
fastapi-forge --help
```

See every project-generation option:

```bash
fastapi-forge create --help
```

Print copy-ready examples:

```bash
fastapi-forge examples
```

Common commands include:

```bash
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:

```bash
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

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

In another terminal:

```bash
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.

```bash
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

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

Review generated output from both variants whenever templates change.

## License

MIT
