Quickstart

This is the first-run experience, start to finish. Nothing here is aspirational; it is the documented make workflow that ships in the download.

Prerequisites

• Python 3.12+ and Node 20+
• make and a Unix-like shell (Windows users should use WSL2)
• PostgreSQL 15+ for production. Local first-run setup can use SQLite, and the Docker path ships PostgreSQL 16.
• A Clerk application (free tier) and a Stripe account (test mode is fine to start)

1. Unzip and install

unzip the-unsexy-stack-professional.zip
cd the-unsexy-stack-professional
make setup

make setup creates the Python virtualenv, installs backend and frontend dependencies, copies .env templates, and runs migrations. If the default Postgres connection is not usable locally, the setup script falls back to SQLite for the first-run dev database. You can switch to Postgres later by changing DATABASE_URL.

2. Configure

Fill in the handful of required environment variables (full reference on the Configuration page):

• DATABASE_URL — defaults to local SQLite after setup fallback; use PostgreSQL for production
• CLERK_SECRET_KEY, CLERK_JWKS_URL, CLERK_ISSUER, CLERK_AUTHORIZED_PARTIES — from your Clerk dashboard
• STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, STRIPE_PRICE_ID — from Stripe (test mode)

Sensible local defaults ship for CORS_ORIGINS, ALLOWED_REDIRECT_HOSTS, and APP_ENV, so you only edit what you must.

3. Confirm or rerun migrations

make migrate

make setup already runs Alembic once. Run make migrate again after you change DATABASE_URL, switch from SQLite to Postgres, or pull a release with new migrations. No hand-written SQL; your schema tracks your models through versioned migrations.

4. Run the stack

make dev

This runs the FastAPI backend and the Next.js 15 frontend together, with the OpenAPI docs served at localhost:8000/docs. No two-terminal dance, no guessing which service starts first. Testing the Stripe webhook path locally? make dev-webhooks adds the Stripe CLI listener.

5. Prove it

make test
# backend: 144 passed (pytest) · frontend: 55 passed (Vitest) · 199 total, 98% backend coverage

Want the slower, real-Postgres integration lane that catches transaction-lifecycle bugs a SQLite-only suite hides? make test-integration. You can confirm the backend count yourself at any time:

cd backend && pytest --collect-only -q | tail -1   # => 144

What you just got

A typed, tested, async FastAPI backend talking to a Next.js 15 frontend, with Clerk auth and Stripe billing already wired, migrations in place, and a green test suite — in about the time it takes to read this page. From here, add your first endpoint and start building the product instead of the plumbing.