Forge is a powerful command-line tool that helps you quickly bootstrap production-ready FastAPI projects with best practices, intelligent defaults, and a beautiful interactive interface.
- 🎨 Beautiful Interactive UI - Stunning terminal interface with gradient colors and smooth animations
- 🚀 Smart Presets - Carefully curated presets for testing, dev tools, deployment, and monitoring
- 🔐 Authentication Ready - Built-in support for JWT authentication (Basic & Complete)
- 🗄️ Database Flexibility - Support for PostgreSQL, MySQL, and SQLite with SQLModel/SQLAlchemy
- 🔴 Redis Integration - Built-in Redis support for caching, sessions, and message queues
- 📋 Background Tasks - Celery integration with Redis broker for async task processing
- 💾 Database Backup - Automated database backup tasks supporting all database types
- 📦 Modular Architecture - Choose only the features you need
- 🧪 Testing Built-in - Pre-configured pytest with async support and coverage
- 🐳 Docker Ready - Production-ready Docker and Docker Compose configurations
- 🔍 Type Safe - Full type hints throughout generated code
- ⚡ Async First - Optimized for FastAPI's async capabilities
- Python 3.9+
- uv package manager
pip install ningfastforgeIf you already have Forge installed, upgrade to the latest version:
pip install --upgrade ningfastforge💡 Tip: Always use the latest version to get new features, bug fixes, and security updates!
# Clone the repository
git clone https://github.com/ning3739/forge.git
cd forge
# Install with uv
uv syncCheck that Forge is installed correctly and see the current version:
forge --version# Interactive mode (recommended)
forge init
# Or specify project name
forge init forge-project
# Non-interactive mode with defaults
forge init forge-project --no-interactivecd forge-project
uv sync
uv run uvicorn app.main:app --reload
# Visit:
http://127.0.0.1:8000/docs # docs
http://127.0.0.1:8000/redoc #redocForge follows a "Configuration-First" design principle with a dynamic generator system:
- Init Command collects user preferences interactively
- Configuration File (
.forge/config.json) is saved first - Dynamic Generator System automatically discovers and executes generators based on configuration
Forge uses a decorator-based system for automatic generator discovery and management:
@Generator(
category="model",
priority=40,
requires=["DatabaseConnectionGenerator"],
enabled_when=lambda c: c.has_auth()
)
class UserModelGenerator:
def generate(self):
# Generate user model codeBenefits:
- ✅ Automatic generator discovery - no manual registration needed
- ✅ Dependency resolution - generators execute in correct order
- ✅ Conditional execution - only enabled generators run
- ✅ Easy extensibility - add new generators by creating files
This separation ensures:
- ✅ Configuration persistence and traceability
- ✅ Clear separation of concerns
- ✅ Easy project regeneration and updates
- ✅ Configuration sharing and templates
- ✅ Modular and maintainable codebase
- PostgreSQL (Recommended) - Robust, feature-rich, excellent for production
- MySQL - Popular, widely supported relational database
- SQLite - Lightweight, serverless database perfect for development and small projects
- SQLModel (Recommended) - Modern, type-safe ORM built on SQLAlchemy and Pydantic
- SQLAlchemy - Mature and powerful ORM with extensive features
- Complete JWT Auth (Recommended) - Full-featured authentication system
- Login & Register
- Email Verification
- Password Reset (Forgot Password)
- Email Service (SMTP)
- Refresh Token
- Basic JWT Auth - Simple authentication
- Login & Register only
- Optional Refresh Token
- CORS (Configurable)
- Rate Limiting (Built-in decorator - auto-included)
- Input Validation (Pydantic - auto-included)
- Password Hashing (bcrypt - auto-included with auth)
- SQL Injection Protection (ORM - auto-included)
- XSS Protection (FastAPI - auto-included)
All projects include:
- Logging - Structured logging with Loguru (automatically included)
- API Documentation - Swagger UI and ReDoc (automatically included)
- Health Check - Basic health check endpoint (automatically included)
- Rate Limiting - Decorator-based rate limiting for API protection (automatically included)
- Redis - In-memory data structure store for caching, sessions, and message queues
- Celery - Distributed task queue for background job processing
- Database Backup - Automated backup tasks supporting MySQL, PostgreSQL, and SQLite
- Task Scheduling - Cron-based task scheduling with Celery Beat (production)
- Standard (Recommended) - Black (formatter) + Ruff (linter)
- None - Skip dev tools
When you enable testing, Forge generates:
- pytest - Testing framework with async support
- httpx - HTTP client for testing
- pytest-cov - Code coverage
- pytest-asyncio - Async test support
Generated Test Files:
tests/conftest.py- Pytest configuration with database fixturestests/test_main.py- Tests for main API endpoints (health check, docs)tests/api/test_auth.py- Authentication endpoint teststests/api/test_users.py- User endpoint tests
Running Tests:
# Run all tests
pytest
# Run with coverage
pytest --cov=app tests/
# Run specific test file
pytest tests/test_main.py
# Run with verbose output
pytest -v- Docker - Dockerfile and docker-compose.yml
- Includes database service configuration
- Production-ready setup
forge-project/
├── app/
│ ├── __init__.py
│ ├── main.py # FastAPI application entry point
│ ├── core/
│ │ ├── __init__.py
│ │ ├── config/ # Configuration management
│ │ │ ├── __init__.py
│ │ │ ├── base.py # Base configuration
│ │ │ ├── settings.py # Settings aggregator
│ │ │ └── modules/ # Config modules (app, database, jwt, cors, email, logger, redis, celery)
│ │ │ ├── __init__.py
│ │ │ ├── app.py
│ │ │ ├── celery.py
│ │ │ ├── cors.py
│ │ │ ├── database.py
│ │ │ ├── email.py
│ │ │ ├── jwt.py
│ │ │ ├── logger.py
│ │ │ └── redis.py
│ │ ├── database/ # Database connection
│ │ │ ├── __init__.py
│ │ │ ├── connection.py
│ │ │ ├── dependencies.py
│ │ │ └── mysql.py # Database-specific connection (mysql/postgresql/sqlite)
│ │ ├── redis.py # Redis connection manager (if Redis enabled)
│ │ ├── celery.py # Celery configuration (if Celery enabled)
│ │ ├── deps.py # Global dependencies
│ │ ├── logger.py # Logging configuration
│ │ └── security.py # Security utilities (password hashing, JWT)
│ ├── decorators/ # Custom decorators
│ │ ├── __init__.py
│ │ └── rate_limit.py # Rate limiting decorator
│ ├── models/ # Database models
│ │ ├── __init__.py
│ │ ├── user.py
│ │ └── token.py # (if refresh token enabled)
│ ├── schemas/ # Pydantic schemas
│ │ ├── __init__.py
│ │ ├── user.py
│ │ └── token.py
│ ├── crud/ # CRUD operations
│ │ ├── __init__.py
│ │ ├── user.py
│ │ └── token.py # (if refresh token enabled)
│ ├── services/ # Business logic
│ │ ├── __init__.py
│ │ └── auth.py
│ ├── tasks/ # Celery tasks (if Celery enabled)
│ │ ├── __init__.py # Task exports
│ │ └── backup_database_task.py # Database backup task
│ ├── routers/ # API routes
│ │ ├── __init__.py
│ │ └── v1/ # API version 1
│ │ ├── __init__.py # Router aggregator
│ │ ├── auth.py
│ │ └── users.py
│ └── utils/ # Utility functions
│ ├── __init__.py
│ └── email.py # (if complete auth enabled)
├── tests/ # Test files (if enabled)
│ ├── __init__.py
│ ├── conftest.py # Pytest configuration and fixtures
│ ├── test_main.py # Main API endpoint tests
│ ├── api/
│ │ ├── __init__.py
│ │ ├── test_auth.py # Authentication tests
│ │ └── test_users.py # User endpoint tests
│ └── unit/ # Unit tests directory
│ └── __init__.py
├── alembic/ # Database migrations (if enabled)
│ ├── versions/ # Migration versions
│ │ └── .gitkeep
│ ├── env.py # Alembic environment
│ ├── script.py.mako # Migration template
│ └── README.md
├── static/ # Static files
│ └── email_template/ # Email templates (if complete auth)
│ ├── base.html
│ ├── verification.html
│ ├── password_reset.html
│ └── welcome.html
├── script/ # Custom scripts directory
├── secret/ # Environment files
│ ├── .env.example # Environment variables template
│ ├── .env.development # Development environment
│ └── .env.production # Production environment
├── .forge/ # Forge configuration
│ └── config.json # Project configuration
├── docker-compose.yml # Docker Compose configuration (if enabled)
├── Dockerfile # Docker configuration (if enabled)
├── .dockerignore # Docker ignore file (if enabled)
├── .gitignore # Git ignore file
├── alembic.ini # Alembic configuration (if migrations enabled)
├── pyproject.toml # Project dependencies
├── uv.lock # UV lock file
├── LICENSE # MIT license
└── README.md # Project documentation
- Database: PostgreSQL with SQLModel
- Migration: Alembic enabled
- Authentication: Complete JWT Auth with Refresh Token
- Caching: Redis enabled
- Background Tasks: Celery with Redis broker
- Security: CORS enabled
- Dev Tools: Black + Ruff
- Testing: pytest with coverage
- Deployment: Docker + Docker Compose
- PostgreSQL for database (production-ready, feature-rich)
- SQLModel for ORM (modern, type-safe, FastAPI-friendly)
- JWT for authentication (stateless, scalable, API-friendly)
- Redis for caching and message queues (fast, reliable)
- Celery for background tasks (mature, scalable)
- Alembic for migrations (industry standard)
Initialize a new FastAPI project with interactive prompts.
# Interactive mode
forge init
# Specify project name
forge init forge-project
# Non-interactive mode (uses defaults)
forge init forge-project --no-interactiveShow the current version of Forge.
forge --version
# or
forge -v✅ PostgreSQL + SQLModel
✅ Complete JWT Auth
✅ Redis + Celery
✅ CORS enabled
✅ Black + Ruff
✅ pytest with coverage
✅ Docker deployment
✅ SQLite + SQLModel
✅ Basic JWT Auth (or no auth)
✅ CORS enabled
✅ Docker deployment
Forge/
├── commands/ # CLI command modules
│ ├── __init__.py # Command exports
│ └── init.py # Project initialization command
├── core/ # Core business logic
│ ├── decorators/ # Decorator system
│ │ └── generator.py # @Generator decorator and registry
│ ├── config_reader.py # Configuration file reader
│ ├── project_generator.py # Project generator
│ ├── generators/ # Code generators
│ │ ├── structure.py # Project structure generator
│ │ ├── orchestrator.py # Dynamic generator coordinator
│ │ ├── configs/ # Config file generators
│ │ ├── deployment/ # Deployment config generators
│ │ └── templates/ # Application code generators
│ └── utils/ # Utility functions
├── ui/ # User interface components
│ ├── colors.py # Color management system
│ ├── components.py # UI components
│ └── logo.py # Logo rendering
├── tests/ # Unit tests (62 tests, 81% coverage)
│ ├── test_init.py # Command initialization tests
│ ├── test_project_generation.py # Project generation tests
│ ├── test_edge_cases.py # Edge cases and error handling
│ ├── test_decorators.py # Decorator system tests
│ └── test_version.py # Version consistency tests
├── main.py # CLI entry point
├── pyproject.toml # Project configuration
└── README.md # This file
@GeneratorDecorator - Automatic generator registration systemorchestrator.py- Discovers and executes generators in correct order- 40+ Generators - Each responsible for specific files/features
- Configuration-First - All decisions driven by
.forge/config.json - Comprehensive Tests - 62 unit tests ensuring reliability
Contributions are welcome! Please feel free to submit a Pull Request.
# Clone the repository
git clone https://github.com/ning3739/forge.git
cd forge
# Install dependencies
uv sync
# Test build
./scripts/test_build.shSee CHANGELOG.md for version history and release notes.
Built with:
- FastAPI - Modern, fast web framework
- Typer - CLI framework
- Rich - Beautiful terminal output
- Questionary - Interactive prompts
For issues, questions, or suggestions, please open an issue on GitHub.
Made with ❤️ for the FastAPI community