Skip to content

setup.md

Latest commit

 

History

History
93 lines (67 loc) · 2.23 KB

setup.md

File metadata and controls

93 lines (67 loc) · 2.23 KB

Developer Setup Guide

This guide covers setting up the Python FastAPI template for local development or GitHub Codespaces.

Prerequisites

  • Python 3.10+
  • pip / pipx
  • Docker (optional — SQLite works without it)

Quick Start (Codespaces)

Open this repo in GitHub Codespaces. The devcontainer installs all dependencies automatically. After the container builds:

./scripts/install.sh   # Set up venv, install deps, init DB
./scripts/dev.sh       # Start dev server with hot-reload

Open http://localhost:8000 in your browser.

Quick Start (local)

git clone <repo-url>
cd <repo-name>

# Install Python dependencies + set up environment
./scripts/install.sh

# Start dev server
./scripts/dev.sh
# → http://localhost:8000

What install.sh Does

  1. Creates .venv/ and installs requirements-dev.txt
  2. Detects Docker contexts
  3. Checks for age / sops (for secrets encryption)
  4. Installs clasi, dotconfig, rundbat via pipx
  5. Resets CLASI history if this is a fresh project from the template
  6. Generates .env from config/dev/public.env + secrets
  7. Runs alembic upgrade head to create the database

Environment Variables

All config is in .env (generated by install.sh). See config/dev/public.env for non-secret defaults and config/dev/secrets.env.example for required secrets.

Variable Default Description
DATABASE_URL sqlite:///./data/dev.db Database connection string
SECRET_KEY (required) Session / token signing key
DEPLOYMENT dev Environment name
APP_NAME Python App Template Display name
DEBUG false Enable debug logging

Switching to Postgres

  1. Start a Postgres container: rundbat create dev
  2. Set DATABASE_URL=postgresql+asyncpg://... in .env
  3. Add asyncpg to requirements.txt
  4. Run alembic upgrade head

Running Tests

python3 -m pytest tests/ -v

Running the Linter

ruff check app/ tests/
ruff format app/ tests/

Database Migrations

# Apply pending migrations
alembic upgrade head

# Create a new migration (after changing app/models.py)
alembic revision --autogenerate -m "describe your change"

# Roll back one step
alembic downgrade -1