Local setup

Requirements

Tool	Version	Used by
Python	3.11 or later	backend/
uv	current	backend/ dependencies and commands
Node.js	22 or later	frontend/, docs/
pnpm	current	frontend/, docs/
Postgres	14 or later	the portal database

Run the portal

1. Create the database user and databases. The tests use factory_test.

   sudo -u postgres psql -c "CREATE ROLE factory LOGIN PASSWORD 'factory' CREATEDB"
   sudo -u postgres psql -c "CREATE DATABASE factory OWNER factory"
   sudo -u postgres psql -c "CREATE DATABASE factory_test OWNER factory"

2. Register the GitHub apps with GitHub apps. Use http://localhost:5173 as APP_BASE_URL.

3. Configure the backend. Create backend/.env from the template in Configuration.

4. Start the backend.

   cd backend
   uv sync
   uv run alembic upgrade head
   uv run uvicorn factory_portal.main:app --port 8000 --reload --timeout-graceful-shutdown 5

   Check it with curl localhost:8000/api/health, which returns {"status":"ok"}. FastAPI’s interactive API docs are at http://localhost:8000/docs.

5. Start the web app in a second terminal. Vite serves the app on port 5173 and forwards /api to the backend, so the browser sees one origin and the session cookie works without CORS.

   cd frontend
   pnpm install
   pnpm dev

6. Open http://localhost:5173 and sign in with GitHub. The first account on a new database becomes the owner; invite other accounts from Settings → Members before they sign in.

Run these docs

cd docs
pnpm install
pnpm dev        # http://localhost:4321

pnpm build writes a static site with a search index to docs/dist/.

Run the checks

Backend

cd backend
uv run pytest

The tests use the factory_test database, a fake GitHub API and a fake Daytona API (respx), so they need no network access or real credentials.

Frontend

cd frontend
pnpm build    # type check and production build
pnpm lint     # oxlint

Docs

cd docs
pnpm openapi  # regenerate public/openapi.json from the backend
pnpm build    # fails on broken pages and config

Database migrations

Alembic owns the schema. After you change backend/src/factory_portal/models.py:

cd backend
uv run alembic revision --autogenerate -m "describe the change"
# Read the generated file in migrations/versions/ and fix it if needed.
uv run alembic upgrade head