FastAPI Project Scaffolder

A command-line tool to generate FastAPI project scaffolds with various database, message broker, and deployment options.

Read the full article on DEV.

Link to the pyPI package: scaffold-fastapi

Features

• Database Support: PostgreSQL, MongoDB, SQLite
• Message Broker: Redis, RabbitMQ
• Deployment Stacks: Minimal, Full (AWS ECS), Serverless
• Production-Ready: Docker, Terraform, Helm charts
• Dependency Management: Uses uv for virtual environments and package installation

Installation

# Install from PyPI
pip install scaffold-fastapi

# Or using uv
uv pip install scaffold-fastapi

# Or using Docker
docker run --rm -it ghcr.io/kenmwaura1/scaffold-fastapi:latest --help

Usage

# Basic usage
scaffold-fastapi my-project --db=postgresql --broker=redis --stack=full

# Interactive mode (will prompt for missing options)
scaffold-fastapi my-project

# Using Docker with volume mount to create project in current directory
docker run --rm -it -v $(pwd):/workspace -w /workspace ghcr.io/kenmwaura1/scaffold-fastapi:latest my-project

Command Options

• --db: Database type (postgresql, mongodb, sqlite)
• --broker: Message broker (redis, rabbitmq)
• --stack: Deployment stack (minimal, full, serverless)

Project Structure

The generated project will have the following structure:

my-project/
├── app/
│   ├── api/
│   │   └── v1/
│   ├── core/
│   ├── db/
│   ├── models/
│   ├── schemas/
│   └── main.py
├── tasks/
│   ├── celery_app.py
│   └── sample_tasks.py
├── infra/
│   ├── docker/
│   ├── terraform/
│   └── helm/
├── tests/
├── .env
├── .env.example
├── Dockerfile
├── docker-compose.yml
└── requirements.txt

Development

# Clone the repository
git clone https://github.com/KenMwaura1/scaffold-fastapi.git
cd scaffold-fastapi

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black .
isort .

CI/CD

This project uses GitHub Actions for:

• Python Tests: Runs tests on Python code, including formatting, linting, and unit tests
• Docker Compose Testing: Validates and tests the generated Docker Compose files
• Container Publishing: Builds and publishes Docker images to GitHub Container Registry
• PyPI Publishing: Automatically publishes to PyPI when pushing to main or creating a tag
• Dependency Updates: Weekly checks and updates dependencies

Publishing to PyPI

To publish this package to PyPI, you need to:

1. Create a PyPI API token (see pypi_instructions.md)
2. Add the token to GitHub Secrets as PYPI_API_TOKEN
3. Push to main or create a tag starting with v (e.g., v0.1.0)

Using the Docker Image

The Docker image is published to GitHub Container Registry and can be used as follows:

# Pull the latest image
docker pull ghcr.io/kenmwaura1/scaffold-fastapi:latest

# Create a new project
docker run --rm -it -v $(pwd):/workspace -w /workspace ghcr.io/kenmwaura1/scaffold-fastapi:latest my-project

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT