DOCSEARCHbyAlgolia
Submit Docs

Full Stack FastAPI Template

repository·master·Indexed 13 days ago

https://github.com/fastapi/full-stack-fastapi-template

A production-ready full-stack boilerplate featuring a FastAPI backend, React frontend, and PostgreSQL database, orchestrated via Docker Compose. Includes SQLModel for ORM, Pydantic for validation, Tailwind CSS and shadcn/ui for styling, and Playwright for E2E testing. Features automatic OpenAPI client generation, Alembic for database migrations, and React Email for template management.

Tokens
17.3K
Snippets
68
Records
92
Agent score
99%

What's inside Full Stack FastAPI Template

  1. Technology Stack Overview

    master

    The Full Stack FastAPI Template uses the following core technologies:

    Backend:

    • FastAPI: Python backend API.
    • SQLModel: ORM for database interactions.
    • Pydantic: Data validation and settings management.
    • PostgreSQL: SQL database.

    Frontend:

    • React: UI framework with TypeScript, hooks, and Vite.
    • Tailwind CSS & shadcn/ui: Styling and component library.
    • Playwright: End-to-end testing.
    • Automatic Client Generation: A frontend client is automatically generated from the backend.

    Infrastructure & DevOps:

    • Docker Compose: Local services and deployment.
    • Traefik: Reverse proxy and load balancer (provides automatic HTTPS).
    • Mailcatcher: Local email testing.
    • Pytest: Backend testing.
    • GitHub Actions: CI/CD.

  2. Frontend Code Structure Overview

    master

    The frontend source code is organized as follows:

    • frontend/src/assets: Static assets.
    • frontend/src/client: The generated OpenAPI client.
    • frontend/src/components: Reusable UI components.
    • frontend/src/hooks: Custom React hooks.
    • frontend/src/routes: Application routes and page components.
    • frontend/src: Main source directory.

  3. Run backend tests

    master

    Tests are managed via Pytest. You can run them in two ways:

    Local execution with uv

    From the backend directory, run the provided test script:

    $ uv run bash ./scripts/test.sh

    Execution inside Docker Compose

    If your stack is already running in Docker, execute the tests inside the backend container. You can pass extra arguments directly to pytest:

    docker compose exec backend bash scripts/tests-start.sh -x

    (The -x flag tells pytest to stop on the first error).

    Test coverage reports are generated as HTML files in htmlcov/index.html.

    # Local
$ uv run bash ./scripts/test.sh

# Inside Docker
$ docker compose exec backend bash scripts/tests-start.sh -x

  4. Manage database migrations with Alembic

    master

    The project uses Alembic to manage SQLModel migrations against the PostgreSQL container. Always create a revision and upgrade the database when changing models in ./backend/app/models.py.

    1. Create a migration revision: Use --autogenerate to detect changes in your SQLModel definitions.
      uv run alembic revision --autogenerate -m "Your message here"
    2. Commit the migration: Add the generated Python files in the alembic directory to your git repository.
    3. Apply the migration: Run the upgrade command to apply changes to the database.
      uv run alembic upgrade head

    Note on disabling migrations: If you prefer not to use migrations, you can uncomment SQLModel.metadata.create_all(engine) in ./backend/app/core/db.py and comment out the alembic upgrade head line in scripts/prestart.sh.

    $ uv run alembic revision --autogenerate -m "Add column last_name to User model"
$ uv run alembic upgrade head

  5. Generate the OpenAPI Frontend Client

    master

    The frontend uses a generated client based on the backend's OpenAPI schema. You must regenerate this client whenever the backend API changes.

    Automatic Method (Recommended): From the project root, run the provided script:

    bash ./scripts/generate-client.sh

    Manual Method:

    1. Ensure the backend is running.
    2. Download the OpenAPI JSON from http://localhost:8000/api/v1/openapi.json.
    3. Save it as openapi.json in the frontend/ directory.
    4. Run the generation command:
    bun run generate-client

  7. Serve the frontend via FastAPI

    master

    You can build the frontend and have it served directly by the FastAPI backend. This is useful for testing the production-like behavior where the backend serves the static assets.

    1. Navigate to the frontend directory.
    2. Build the project:
      bun run build

    The build output is written to backend/app/frontend and will be accessible at http://localhost:8000.

    bun run build

  8. Set up GitHub Actions Self-Hosted Runner

    master

    To enable Continuous Deployment (CD), install a GitHub Actions runner on your remote server.

    1. Create a dedicated user:
      sudo adduser github
sudo usermod -aG docker github
sudo su - github
    2. Install the runner: Follow the official GitHub guide inside the github user's home directory. When prompted for labels, use the environment name (e.g., production).
    3. Install as a service (to ensure it runs on startup): Exit the github user, become root, and run:
      cd /home/github/actions-runner
./svc.sh install github
./svc.sh start
    4. Check status:
      ./svc.sh status

  9. Copy Code to Remote Server

    master

    Use rsync to transfer your project code to the remote server. The following command uses --filter=":- .gitignore" to ensure that files ignored by git (like local virtual environments) are not uploaded.

    rsync -av --exclude=".git/" --filter=":- .gitignore" ./ root@your-server.example.com:/root/code/app/

  10. Customize and preview email templates

    master

    Email templates are built using [React Email] in ./packages/react-email/.

    Workflow

    1. Edit components: Modify components in ./packages/react-email/emails/ or shared UI in ./packages/react-email/ui/.
    2. Preview: To see changes in real-time, run the email dev server from the project root:
      bun run email:dev
    3. Add placeholders: If you need new data in an email, add a Jinja placeholder (e.g., {{ new_var }}) to the component props and update the corresponding generate_*_email() function in ./backend/app/utils.py.
    4. Export: Once editing is complete, regenerate the HTML templates used by the backend:
      bun run email:export

    Warning: Do not edit the rendered HTML files in ./backend/app/email-templates/ manually; they are generated from the React components.

    # Preview emails
$ bun run email:dev

# Export templates to backend
$ bun run email:export

  11. How to update from the original template

    master

    To pull the latest changes from the original template into your modified repository without automatically merging them, use the upstream remote. This allows you to inspect changes and resolve conflicts manually before committing.

    # Pull latest changes from upstream without committing
git pull --no-commit upstream master

# After resolving conflicts in your editor:
git merge --continue

  12. Set up local development environment

    master

    For local development, run supporting services (PostgreSQL and Mailcatcher) via Docker Compose, then run the FastAPI and Vite development servers locally on your machine.

    1. Start supporting services:

      docker compose up -d db mailcatcher

    2. Prepare the backend: Navigate to the backend directory, install dependencies, and run the prestart script:

      uv sync
uv run bash scripts/prestart.sh

    3. Start the FastAPI server:

      uv run fastapi dev

    4. Start the frontend: Navigate to the project root, install dependencies, and start the Vite server:

      bun install
bun run dev

    Development URLs:

    • Frontend: http://localhost:5173
    • Backend API: http://localhost:8000
    • Swagger UI: http://localhost:8000/docs
    • Mailcatcher: http://localhost:1080
    docker compose up -d db mailcatcher

# In backend/
uv sync
uv run bash scripts/prestart.sh
uv run fastapi dev

# In project root/
bun install
bun run dev