FastAPI starter package for students prototyping AI web applications. Pre-built admin components give FastAPI functionality comparable to Django for AI-first applications.

Django and Flask are not designed for optimized async LLM applications.

Although both Django and Flask can absolutely be used for complex AI applications and are great in many, many ways, there are often rough patches during development of asynchronous AI applications that communicate with backend LLMs available at OpenAI, Anthropic, and OpenRouter.

FastAPI has advantages in future-proof architecture, but can have a steep learning curve for people, especially for developers familiar with Django.

FastOpp provides an opinionated framework for FastAPI with the following features:

• admin panel similar to Django with role-based authentication
• SQL database with Django-inspired models and migrations
• Django-style HTML templates with modern UI components
  • Replaceable style templates to get started
• API endpoints to connect to other frontend frameworks
  • auto-generated documentation for API endpoints
  • designed to connect to Flutter and React in the future, but we do not have examples
• oppman.py core management tool for database, users, and application setup
• oppdemo.py demo file management tool for switching between demo and minimal modes

This stack is opinionated and may not be for you. It is intended for students and novice developers who know Python, but are not strong in or do not like JavaScript.

FastOpp is not intended for production use or for experienced developers.

• You strongly prefer Python over JavaScript on the backend
• You prefer to handle logic on the Python backend instead of using JavaScript code on the frontend
• You prefer inline styling instead of separation of concerns with CSS in separate files
• You prefer typed languages and want to use Python optional type hints instead of relying only on dynamic typing
• You prefer HTML files with Python code and variables embedded in the HTML instead of embedding HTML in the Python code on the server
• You are using Django or Flask and are having problems with async LLM communication
• You started with Streamlit or Gradio. Your code became more complex and is now difficult to manage

• University student looking to build resume - Show potential employers that you can build an AI application. You want to host it cheaply and use cheap or free LLMs with the option to use a higher-quality LLM before you showoff your project. You have an idea on how to use AI and want to show it to people.
• Hobbyist looking to vibe code simple AI utility - Provide Cursor or equivalent access to demos and start with an opinionated structure for files and UI. Enforce vibe-code behavior with rules so that you can go back and edit your code. Deploy cheaply for less than $1 and month and scale up if your idea take off.
• Small business entrepreneur - You have great business ideas, but you are not a great programmer. You want to put AI into a business workflow that you are familiar with and show other people to get more help.

The project is intended to teach use of FastAPI with LLMs. The knowledge you gain will be highly relevant to employers as long as Python and LLMs continue to be used together. We intend that you eventually move off of Jinja2 templates and use the built-in API for interfaces with React-variants or something like Flutter for mobile or web apps. The project is intended to get you started on your path. Even if it dies, your knowledge will live on.

To be honest, we are not confident in the security architecture and model. It is sufficient for learning purposes, but you need to look into security yourself and use another model if your project takes off. FastOpp will get you started quickly, but it is not intended for long-term production use.

Yes. We use SQLite to get you started because there are less installation dependencies. If you use the database in production, we recommend switching to PostgreSQL.

Yes. We use FastAPI in deployment tutorials to get you started. NGINX is better. FastAPI is very usable without NGINX if you do not have many simultaneous users.

Yes. The free LLM is set for easy setup. We do not use it in production.
At a minimum, you should change this to the paid version of LLama3.3-70b-instruct or your app will have very limited functionality. If you password-protect your app, you can control costs. If only a few people use the app, the free version will work. LLama3.3-70b is pretty good, not great. It's primary quality is that it is much cheaper than top-tier great LLMs like GPT-5.

Yes. FastOpp itself is under the MIT license. You can modify FastOpp and close it off if that helps your business or personal goals. Refer to pyproject.toml for a list of FastOpp dependencies and confirm compliance for your use.

FastOpp can be viewed as an opinionated design framework that adds an UI to an SQL database (or vector db with extensions) and a UI to the input and output of an LLM.

Admin panel is restricted to logged-in users.

FastOpp comes with an optional basic UI design system to accelerate AI application development.

• based on Tailwind CSS, DaisyUI, AlpineJS and HTMX

• Python 3.12+ If Python 3.12+ is not on your Mac, consider installing pyenv and install the newest 3.12.x with pyenv. Although the latest stable Python is 3.13.7, we're using 3.12.x right now for maximum package compatibility.
• uv package manager

Fork it!

Go to https://github.com/Oppkey/fastopp
Click Fork in GitHub UI
You'll get github.com/yourusername/fastopp

Clone your fork down to your local machine

git clone https://github.com/yourusername/fastopp.git
cd fastopp

Add upstream remote

git remote add upstream https://github.com/Oppkey/fastopp.git

Sync your fork with upstream before new work

git fetch upstream
git checkout main
git merge upstream/main

Create a .env file in your project root:

Required Environment Variables:

• DATABASE_URL: Database connection string
• SECRET_KEY: Secret key for JWT tokens and session management
• ENVIRONMENT: Set to "development" for development mode
• OPENROUTER_API_KEY: API key for OpenRouter (required for AI demo features)

Optional Environment Variables:

• UPLOAD_DIR: Directory for storing uploaded files (defaults to static/uploads if not set)
  • Local Development: Not set (uses default static/uploads)
  • Production Deployments: Set to persistent storage path (e.g., /data/uploads, /app/uploads)
  • URL Compatibility: Files are always served from /static/uploads/photos/ regardless of storage location

Recommended: Use the built-in secret generator for maximum security:

# Generate a cryptographically secure SECRET_KEY
uv run python oppman.py secrets

This will output a line like SECRET_KEY=... that you can copy directly into your .env file.

Alternative methods:

# Create environment file with secure defaults
cat > .env << EOF
DATABASE_URL=sqlite+aiosqlite:///./test.db
SECRET_KEY=$(uv run python oppman.py secrets | grep SECRET_KEY | cut -d'=' -f2)
ENVIRONMENT=development
OPENROUTER_API_KEY=your_openrouter_api_key_here
EOF

Using the example configuration:

# Copy the example environment file
cp example.env .env

# Edit the .env file with your values
nano .env  # or use your preferred editor

The example.env file contains all available configuration options with detailed comments and examples.

Or manually create .env:

# .env
DATABASE_URL=sqlite+aiosqlite:///./test.db
SECRET_KEY=your_generated_secret_key_here
ENVIRONMENT=development
OPENROUTER_API_KEY=your_openrouter_api_key_here

⚠️ Security Important:

• Never commit .env files to version control
• Add .env to your .gitignore file
• Keep your SECRET_KEY secure and private
• Use different SECRET_KEYs for different environments

# Complete setup with one command
uv run python oppdemo.py init

This single command will:

• Initialize migrations
• Create initial migration
• Apply migrations
• Initialize database with sample data
• Create superuser and test data

If you prefer to understand each step:

# Initialize migrations (first time only)
uv run python oppman.py migrate init

# Create initial migration
uv run python oppman.py migrate create "Initial migration"

# Apply migrations
uv run python oppman.py migrate upgrade

# Initialize database with sample data
uv run python oppdemo.py init

Note: Demo data initialization commands have been moved from oppman.py to oppdemo.py for better separation of concerns.

# Start the server
uv run python oppman.py runserver

Visit these URLs in your browser:

• Homepage: http://localhost:8000/
• Admin Panel: http://localhost:8000/admin/
• API Docs: http://localhost:8000/docs

Use these credentials to access the admin panel:

• Email: admin@example.com
• Password: admin123

FastOpp now uses two separate management tools for better organization and separation of concerns:

oppman.py is similar to Django's manage.py and focuses on core application management:

# Server management
uv run python oppman.py runserver       # Start development server
uv run python oppman.py stopserver      # Stop development server
uv run python oppman.py production      # Start production server

# Database management
uv run python oppman.py backup          # Backup database
uv run python oppman.py delete          # Delete database (with backup)

# Migration management
uv run python oppman.py migrate init    # Initialize migrations
uv run python oppman.py migrate create "Add new table"  # Create migration
uv run python oppman.py migrate upgrade # Apply migrations
uv run python oppman.py migrate current # Check migration status

# Environment and utilities
uv run python oppman.py env             # Check environment configuration
uv run python oppman.py secrets         # Generate SECRET_KEY for .env file
uv run python oppman.py demo            # Show demo command help
uv run python oppman.py help            # Show comprehensive help

oppdemo.py handles all demo-related functionality:

# Demo file management
uv run python oppdemo.py save           # Save demo files to demo_assets
uv run python oppdemo.py restore        # Restore demo files from backup
uv run python oppdemo.py destroy        # Switch to minimal application
uv run python oppdemo.py diff           # Show differences between current and backup
uv run python oppdemo.py backups        # List all available backups

# Demo data initialization (moved from oppman.py)
uv run python oppdemo.py init           # Complete initialization (database + superuser + users + products + webinars + registrants)
uv run python oppdemo.py db             # Initialize database only
uv run python oppdemo.py superuser      # Create superuser only
uv run python oppdemo.py users          # Add test users only
uv run python oppdemo.py products       # Add sample products only
uv run python oppdemo.py webinars       # Add sample webinars only
uv run python oppdemo.py download_photos # Download sample photos
uv run python oppdemo.py registrants    # Add sample registrants
uv run python oppdemo.py clear_registrants # Clear and add fresh registrants
uv run python oppdemo.py check_users    # Check existing users
uv run python oppdemo.py test_auth      # Test authentication
uv run python oppdemo.py change_password # Change user password
uv run python oppdemo.py list_users     # List all users

# Help
uv run python oppdemo.py help           # Show comprehensive help

# Development server
uv run python oppman.py runserver       # Start development server
uv run python oppman.py stopserver      # Stop development server

# Production server (optional)
uv run python oppman.py production      # Start production server

# Initialize migrations (first time only)
uv run python oppman.py migrate init

# Create new migration
uv run python oppman.py migrate create "Add new table"

# Apply migrations
uv run python oppman.py migrate upgrade

# Check migration status
uv run python oppman.py migrate current

# View migration history
uv run python oppman.py migrate history

# Check environment configuration
uv run python oppman.py env

# Generate secure SECRET_KEY for .env file
uv run python oppman.py secrets

# Show all available commands
uv run python oppman.py help

Backup files are automatically organized in the backups/ directory:

• backups/destroy/ - Files backed up before switching to minimal mode
• backups/restore/ - Files backed up before restoring demo mode

Each backup includes a timestamp for easy identification. Use uv run python oppdemo.py backups to list all available backups.

The application comes with pre-loaded test data:

• Superuser: admin@example.com / admin123
• Test Users: john@example.com, jane@example.com, bob@example.com / test123

Sample products with various categories and prices for testing the admin interface.

FastOpp now uses two separate management tools for better organization and separation of concerns:

oppman.py is similar to Django's manage.py and focuses on core application management:

• Server Management: Start/stop development and production servers
• Database Management: Backup, delete, and migration operations
• Environment Management: Configuration checks and utilities
• Core Operations: Essential application lifecycle management

oppdemo.py handles all demo-related functionality:

• Demo File Management: Save/restore demo state, switch between demo and minimal modes
• Demo Data Initialization: All sample data creation (users, products, webinars, registrants)
• Demo State Control: Comprehensive demo application management

1. Add/Modify Models: Edit models.py with your changes
2. Create Migration: uv run python oppman.py migrate create "Description"
3. Review Migration: Check the generated file in alembic/versions/
4. Apply Migration: uv run python oppman.py migrate upgrade
5. Verify: uv run python oppman.py migrate current

Create a feature branch

git checkout -b feature/your-change

Make changes → commit

git add .
git commit -m "Your change description"

Push feature branch to your fork

git push origin feature/your-change

Open a Pull Request (PR)

In GitHub, go to your fork yourusername/fastopp.
Click “Compare & pull request”.

Base: Oppkey/fastopp:main
Head: yourusername/fastopp:feature/your-change

Fill title, description, link issues. Submit.

If upstream changes during review, sync your branch

git fetch upstream
git checkout feature/your-change
git merge upstream/main
git push origin feature/your-change

After PR is merged

git checkout main
git fetch upstream
git merge upstream/main
git branch -d feature/your-change
git push origin --delete feature/your-change

1. "Alembic not found"

   uv add alembic

2. "Alembic not initialized"

   uv run python oppman.py migrate init

3. Environment issues

   # Check environment configuration
   uv run python oppman.py env

4. Database issues

   # Backup and reset
   uv run python oppman.py backup
   uv run python oppman.py delete
   uv run python oppman.py init

5. "Module not found" errors

   # Reinstall dependencies
   uv sync

6. Port already in use

   # Stop any running servers
   uv run python oppman.py stopserver
   
   or
   
   # Kill uvicorn processes manually
   pkill -f uvicorn
   
   or
    
   # use a different port
   uv run uvicorn main:app --reload --port 8001

FastOpp is a learning tool designed for tinkering, you can play around with the demo and then restore the entire demo or just the database to a working state:

# Backup current database
uv run python oppman.py backup

# Delete database and reinitialize
uv run python oppman.py delete # delete SQL database

# initialize blank database
uv run python oppdemo.py db

or

# initializes and puts in fake data
uv run python oppdemo.py init 

# Verify setup
uv run python oppman.py env

FastOpp includes a flexible file upload system that works across different deployment environments:

• Local Development: Files stored in static/uploads/ directory (default behavior)
• Production Deployments: Files stored in configurable directory via UPLOAD_DIR environment variable
• URL Consistency: All uploads served from /static/uploads/photos/ regardless of storage location

# Local development (no environment variable needed)
# Files stored in: static/uploads/photos/
# URLs served from: /static/uploads/photos/

# Docker deployment
UPLOAD_DIR=/app/uploads
# Files stored in: /app/uploads/photos/
# URLs served from: /static/uploads/photos/

# Fly.io deployment with persistent Fly Volume mounted at /data
UPLOAD_DIR=/data/uploads
# Files stored in: /data/uploads/photos/
# URLs served from: /static/uploads/photos/

# Kubernetes deployment
UPLOAD_DIR=/persistent/uploads
# Files stored in: /persistent/uploads/photos/
# URLs served from: /static/uploads/photos/

• Environment-agnostic: Works in any deployment environment
• Backward compatible: Local development unchanged
• Persistent storage: Production deployments can use persistent volumes
• URL consistency: Frontend code doesn't need to change

FastOpp supports two application modes:

• Full-featured application with AI chat, dashboard, design examples
• Sample data and comprehensive UI components
• Ideal for learning and showcasing features

• Basic FastAPI application with authentication
• Clean slate for building your own application
• Includes admin panel and basic structure with password-protected pages

# Save current demo state
uv run python oppdemo.py save

# Switch to minimal mode
uv run python oppdemo.py destroy

# Restore demo mode
uv run python oppdemo.py restore

# Check what's different
uv run python oppdemo.py diff

• FastAPI for AI LLM Apps with SQLAdmin, SQLModel - Quickstart Template for Frontend - published August 15, 2025
• FastAPI with LLM and Database Beginner Tutorial - published August 18, 2025
• Deploy FastAPI and SQLite to Fly for Cheap Hosting - published August 26, 2025
• Permanent Photo Uploads on Fly with FastAPI Static Files on Fly Volume - published August 29, 2025
• Free FastAPI Deployment - No Credit Card - Railway - published Sept 3, 2025
• FastAPI Deploy to Leapcell - free hosting tier
• Free Deploy to Leapcell with FastAPI, PostgreSQL and Object Storage

• Add new page
• Change LLM

• Deploy to fly.io
• fly deployment costs discussion

• Architecture Overview - MVS Architecture and code organization
• Database
• Authentication
• Emergency Access - Password recovery system for admin access
• Features

• beautiful
• cheap
• easy
• opinionated