Skip to content

Installation Guide

Set up your boilerplate in minutes.

Prerequisites

Install these tools first:

Recommended IDE: Cursor (AI Velocity) or VS Code

Quick Install

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# 1. Extract your tier zip
unzip your-tier-boilerplate.zip
cd your-tier-boilerplate

# 2. Complete automated setup
task full-setup

# 3. Create environment file
cp local.env.example local.env
# Edit local.env with your values

# 4. Start development
task run-backend     # Terminal 1 (port 8020)
task run-frontend    # Terminal 2 (port 5173)

Access:

  • Frontend: http://localhost:5173
  • Backend API: http://localhost:8020
  • API Docs: http://localhost:8020/docs
  • Admin Panel (Top G+): http://localhost:8020/admin/

Detailed Setup

1. Install Dependencies

Backend:

Bash
1
poetry install

Frontend:

Bash
1
2
cd frontend
npm install

Or use Task:

Bash
1
2
task install          # Backend
task install-frontend # Frontend

2. Environment Configuration

Create local.env from example:

Bash
1
cp local.env.example local.env

Required variables:

Text Only
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
# Database
db_username=craftyourstartup
db_password=craftyourstartup
db_host=localhost
db_port=54323
db_database=craftyourstartup

# Security
secret_key=dev-secret-key-change-in-production

# URLs
domain=http://localhost:5173
redirect_after_login=http://localhost:5173/dashboard

Top G+ also configure:

Text Only
1
2
3
4
# Stripe
STRIPE_SECRET_KEY=sk_test_...
STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

Configuration guide

3. Database Setup

Start PostgreSQL:

Bash
1
task db:docker-start

Wait 10 seconds for PostgreSQL to start, then apply migrations:

Bash
1
task db:migrate-up

4. Start Development Servers

Backend:

Bash
1
2
task run-backend
# Starts on: http://localhost:8020

Frontend:

Bash
1
2
task run-frontend
# Starts on: http://localhost:5173

5. Create First User (Optional)

Top G+ (for admin panel):

Bash
1
2
3
4
task db:user-create -- \
  --email [email protected] \
  --password admin123 \
  --full_name "Admin User"

Or use signup page: Visit http://localhost:5173/signup

6. Payment Setup (Top G+ Only)

Bash
1
2
3
# Configure Stripe in local.env first
# Then initialize products
task payments:setup

Payment setup guide

Verify Installation

Check Backend

Bash
1
2
3
4
# Test backend health
curl http://localhost:8020/health

# Should return: {"status":"healthy"}

Check Frontend

Visit http://localhost:5173 - should see landing page

Check Database

Bash
1
2
# Check database status
task db:migrate-status

Check API Docs

Visit http://localhost:8020/docs - should see OpenAPI documentation

Common Issues

Python version wrong

Bash
1
2
3
4
5
6
# Check version
python --version  # Should be 3.11+

# If using pyenv
pyenv install 3.11.0
pyenv local 3.11.0

Poetry not found

Bash
1
2
3
4
5
# Install Poetry
curl -sSL https://install.python-poetry.org | python3 -

# Verify
poetry --version

Database connection fails

Bash
1
2
3
4
5
6
7
8
9
# Ensure Docker running
docker ps

# Restart database
docker-compose down
docker-compose up -d

# Wait 10 seconds
task db:migrate-up

Port already in use

Bash
1
2
3
4
5
# Kill process on port 8020 (backend)
lsof -ti:8020 | xargs kill -9

# Kill process on port 5173 (frontend)
lsof -ti:5173 | xargs kill -9

Task command not found

Bash
1
2
3
4
5
6
7
8
9
# Install Task
# macOS
brew install go-task/tap/go-task

# Linux
sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d

# Windows
choco install go-task

More troubleshooting

Next Steps

  1. Configure environment
  2. Explore features
  3. Set up payments (Top G+): Stripe guide
  4. Set up AI tools (AI Velocity): AI development

Available Task Commands

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
# Development
task run-backend           # Start FastAPI
task run-frontend          # Start Vite
task frontend:generate-client  # Update TypeScript client

# Database
task db:docker-start       # Start PostgreSQL
task db:migrate-up         # Apply migrations
task db:migrate-create -- "description"  # Create migration
task db:user-create        # Create superuser (Top G+)

# Payments (Top G+)
task payments:setup        # Initialize Stripe
task payments:products-create  # Create products

# Testing
task quality:test          # Run all tests
task quality:lint          # Lint code

# Full list
task --list

Tech Stack

  • Backend: FastAPI + SQLModel + PostgreSQL + Alembic
  • Frontend: React 18 + TypeScript + Vite + Material-UI v6
  • Auth: JWT + Google OAuth
  • State: TanStack React Query
  • Dev: Poetry + Task + Docker

Learning Resources

New to FastAPI? Learn FastAPI for free with interactive tutorials.