Getting Started

This template provides a modern, full-stack web application architecture using FastAPI, React, SQLModel, and PostgreSQL. It is designed for rapid development with a focus on security, scalability, and developer experience.

Prerequisites

Before you begin, ensure you have the following installed:

• Python: ^3.10
• Docker and Docker Compose
• uv: For Python package and environment management.
• Bun: (Recommended) or Node.js for frontend development.

Installation

The fastest way to get started is by using Docker Compose, which sets up the backend, frontend, database, and proxy automatically.

1. Clone the repository:

   git clone https://github.com/fastapi/full-stack-fastapi-template.git my-project
   cd my-awesome-project

2. Configure environment variables: Copy the example .env file and update the required secrets.

   cp .env.example .env

   At a minimum, you should update:

   • SECRET_KEY: Generate one using python -c "import secrets; print(secrets.token_urlsafe(32))"
   • FIRST_SUPERUSER_PASSWORD: Password for the initial admin user.
   • POSTGRES_PASSWORD: Password for the database.

3. Start the stack:

   docker compose watch

   This command starts all services and enables "watch mode," which automatically syncs code changes from your local machine to the running containers.

Quick Start

Once the stack is running, you can access the following services:

• Frontend Dashboard: http://localhost:5173
• Backend API: http://localhost:8000
• Interactive API Docs (Swagger UI): http://localhost:8000/docs
• Database Admin (Adminer): http://localhost:8080
• Mailcatcher (Email Testing): http://localhost:1080

Login Credentials

Use the values you set in your .env file:

• Username: admin@example.com (default)
• Password: (The value of FIRST_SUPERUSER_PASSWORD)

Configuration

The application is configured via environment variables defined in the root .env file. Key variables include:

Variable	Description	Default
PROJECT_NAME	The name of your project	FastAPI Project
STACK_NAME	Used for Docker labels and project naming	fastapi-project
ENVIRONMENT	Deployment environment (local, staging, production)	local
DOMAIN	Base domain for the application	localhost
VITE_API_URL	Frontend variable to point to the API	http://localhost:8000

Verify Installation

To ensure everything is set up correctly, you can run the end-to-end tests using Playwright.

1. Ensure the backend is running:

   docker compose up -d --wait backend
2. Run the tests from the root directory:

   bunx playwright test

Other Install Options

Local Development (No Docker)

If you prefer to run the services directly on your host machine for faster iteration:

Backend Setup:

cd backend
uv sync
source .venv/bin/activate
fastapi dev app/main.py

Frontend Setup:

cd frontend
bun install
bun run dev

Next Steps

• Data Architecture — Learn how to add new API endpoints and models.
• UI Framework & Theming — Explore the React component structure and TanStack Router.
• Dockerized Deployment Architecture — Instructions for deploying to production using Traefik and HTTPS.