Getting Started

This is the mechanical path — click here, run this, see it work. For the why behind the stack and the ground rules for using AI on this project, see Using This Template.

1. Create your repo

On cmx-learn/fastapi-template, click Use this template → Create a new repository. This gives you your own repo with clean history, not a fork — you won’t accidentally open PRs back to the original template.

2. Set your secrets first

Codespaces secrets only get injected into a codespace at creation time. Set these under your repo (or org) Settings → Secrets and variables → Codespaces before you create the codespace — if you add one afterward, stop and restart the codespace for it to take effect.

At minimum, you need:

Secrets	Covered in
POSTGRES_SERVER, POSTGRES_PORT, POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD	Database Setup
SECRET_KEY, FIRST_SUPERUSER, FIRST_SUPERUSER_PASSWORD	Environment Variables

SMTP_* is optional — skip it for now and add it later, once you actually need password-reset emails to send.

3. Open in Codespaces

Code → Create codespace on main. The devcontainer builds automatically and installs uv, bun, Claude Code, and Codex CLI, then runs uv sync and bun install for you. GitHub’s free tier (120 core-hours/month, ~60 hours on the default machine) is enough to get started on.

Nothing to install by hand

Wait for the “Setting up…” step to finish before running anything — that’s the devcontainer’s postCreateCommand doing the install. Once it’s done, both AI CLIs and both toolchains are ready in the terminal.

4. Run the first migration

The database has no tables yet:

cd backend && uv run alembic upgrade head

5. Point the frontend at the backend

Running both dev servers separately means the frontend (port 5173) and backend (port 8000) are different origins — without telling it otherwise, the frontend calls itself for API requests and every request 404s. Point it at the backend’s forwarded Codespaces URL:

echo "VITE_API_URL=https://${CODESPACE_NAME}-8000.${GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN}" > frontend/.env

If that env var comes back empty

Check the Ports tab for the exact forwarded URL of port 8000 and paste it in manually as VITE_API_URL instead — same file, same effect.

6. Start both dev servers

Two terminals:

cd backend && fastapi run --reload app/main.py

bun run dev

Codespaces forwards ports 8000 (backend) and 5173 (frontend) automatically — check the Ports tab, or accept the popup to open the frontend in your browser.

7. Log in

Use the FIRST_SUPERUSER / FIRST_SUPERUSER_PASSWORD you set as secrets in step 2 — that account is created automatically on first backend startup.

8. Start building with AI

Run claude or codex in the terminal. Both are already wired to Serena and Spec Kit at the project level — nothing left to configure. Start with Spec-Driven Development for how to kick off a feature, and Code Navigation with Serena for what to ask it.