Getting Started

This guide gets you from a fresh clone to a fully running local SeedTrust environment. All three services and the background worker start from a single command.

Prerequisites

Install these once on your machine before doing anything else.

Tool	Why	Install
uv	Python package manager — runs everything Python-related	`curl -LsSf https://astral.sh/uv/install.sh \| sh`
Docker	Runs the local MySQL database	docs.docker.com/get-docker
Node.js 20+	Required for the Next.js frontend	nodejs.org
pnpm	Node package manager used by the frontend	`npm install -g pnpm`

uv is the only hard requirement to start. If you already have a configured .env and a running database, uv run st run dev is all you need.

First-Time Setup

Do this once after cloning the repository. Skip to Daily Use if your environment is already configured.

1. Configure environment variables

Copy the example env file and fill in the required values. Ask a teammate for the actual secret values.

cp .env.example .env

Minimum required variables in .env:

DB_CRYPT_KEY=        # Encryption key for sensitive database fields
SECRET_KEY=          # Flask/FastAPI application secret
SYSTEM_EMAIL=        # Admin notification email address
INTERNAL_API_KEY=    # Internal service-to-service API key
VAPID_PRIVATE_KEY=   # Web push notification private key
VAPID_PUBLIC_KEY=    # Web push notification public key
ACH_KEY=             # ACH payment data encryption key

The Next.js frontend also needs app/.env:

cp app/.env.example app/.env

Minimum required variables in app/.env:

BACKEND_API_URL=http://localhost:8000   # Points to the local FastAPI service
AUTH_SECRET=                            # NextAuth.js session secret (any random string locally)

2. Start the database

uv run st db start

This starts a MySQL 8.0 Docker container on port 3306. No password required locally.

3. Run database migrations

uv run st db migrate upgrade

This applies all pending Flask migrations to the local database.

4. Seed the database

uv run st db seed

This creates the initial data: admin user, agencies, case stages, email templates, and sample cases. You’ll be prompted to enter your admin user credentials.

Daily Use

Once set up, starting everything is one command:

uv run st run dev

That’s it. uv handles installing all Python dependencies automatically on first run.

What’s Running

After st run dev, four processes start in parallel:

Service	URL	What It Does
Flask	`http://localhost:<PORT>`	Legacy backend — serves the desktop admin and client UI
FastAPI	`http://localhost:8000`	Modern API — serves the mobile PWA
Next.js	`http://localhost:3002`	Mobile PWA frontend
Huey Worker	(no URL — background process)	Processes background jobs and async tasks

Flask port: The Flask port is set by your local .env file. Common values are :3000 and :5001. Check the PORT or FLASK_RUN_PORT variable in your .env if you’re unsure which port it will start on.

FastAPI interactive docs (useful for exploring or testing API endpoints):

Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc

Output from each service is prefixed and color-coded in the terminal:

[flask] — green
[fastapi] — blue
[next] — yellow
[worker] — yellow

Press Ctrl+C to stop all services at once.

Most developers don’t need the Huey worker. It only matters if you’re testing background jobs specifically. Skip it by default:
Terminal window
uv run st run dev --no-worker

Running a Single Service

If you’re only working on one part of the stack:

uv run st run flask      # Flask only — port comes from PORT/FLASK_RUN_PORT in .env
uv run st run fastapi    # FastAPI only — port 8000
uv run st run nextjs     # Next.js only — port 3002
uv run st run worker     # Huey background worker only

You can also exclude services from dev mode:

uv run st run dev --no-flask --no-worker   # Skip Flask and the background worker

Running Tests

uv run st run tests

This runs both the Flask and FastAPI test suites. FastAPI tests run against an in-memory SQLite database — no running MySQL required.

To run just one suite:

cd seedtrust_flask && uv run pytest

cd seedtrustapi && uv run pytest

Database Commands

uv run st db start           # Start MySQL Docker container (port 3306)
uv run st db stop            # Stop MySQL Docker container
uv run st db migrate upgrade # Apply pending Flask migrations
uv run st db seed            # Seed initial data (destructive — confirms before running)

Database Configuration

The CLI supports multiple named database environments (local, staging, etc.) stored in .env.dbs at the repo root. Switching environments rewrites the connection strings in seedtrust_flask/.env and seedtrustapi/.env automatically.

uv run st db info              # Show active environment and connection status
uv run st db config show       # List all configured environments
uv run st db config set        # Interactive picker — choose from configured environments
uv run st db config set local  # Switch directly to a named environment
uv run st db config add        # Add a new environment interactively

Most developers only ever use local. You’ll need to switch environments if you’re testing against a shared database or running a one-off migration on staging.

Fixing Migration Issues

Multiple heads

This happens when two branches each added a migration and were then merged. The DB has two competing “tips” in the migration history.

uv run st db migrate heads     # See all current heads
uv run st db migrate merge     # Create a merge migration (interactive)
uv run st db migrate upgrade   # Apply the merge

Unknown or diverged state

If the DB revision doesn’t match what’s in code (e.g., after a hard reset or branch switch):

uv run st db migrate status    # Check what revision the DB is currently at
uv run st db migrate upgrade   # Re-apply forward

Full local reset

If things are badly out of sync and you want a clean slate (local only):

uv run st db reset             # Drops all tables (localhost only — confirms before running)
uv run st db migrate upgrade   # Re-apply all migrations from scratch
uv run st db seed              # Re-seed with dev data

Never run st db reset against staging or production. The command blocks on non-local hosts.

Troubleshooting

uv: command not found uv was not added to your PATH after install. Run source ~/.bashrc (or ~/.zshrc) or open a new terminal.

Database connection refused Make sure Docker is running and the MySQL container is up: docker ps | grep seedtrust-mysql. If not running, uv run st db start.

Next.js fails to start pnpm may not be installed. Run npm install -g pnpm and try again. The CLI runs pnpm install automatically on first start.

Missing environment variable errors on FastAPI startup The FastAPI service logs which variable is missing. Check your .env file against the list in First-Time Setup above.

Flask DB_CRYPT_KEY warning Flask will warn on startup if DB_CRYPT_KEY is missing. Encrypted fields (ACH forms, banking data) will not work without it. Make sure it is set in .env.