Local setup

Get the full stack running from a fresh clone. This is the short path; the exhaustive reference is the README. Status: current.

Requirements

Tool	Why
Bun ≥ 1.4	Runtime and package manager for every workspace
Docker + Compose	PostgreSQL on 127.0.0.1:5434 (and optional app containers)
Git
Optional: devenv/Nix	provides Node 22 + Bun if you use direnv

Node is only needed for Fern (SIGARRA SDK regeneration), not for day-to-day development.

Fresh clone

Every command runs from the repository root unless a cd is shown.

git clone git@github.com:NIAEFEUP/tts.git
cd tts

# 1. all workspaces: backend, frontend, sigarra
bun install

# 2. PostgreSQL 16 on 127.0.0.1:5434 (user/password/db = tts/tts/tts)
docker compose up -d --wait

# 3. env files (git-ignored; .env.schema holds working defaults)
cp apps/backend/.env.schema  apps/backend/.env
cp apps/frontend/.env.schema apps/frontend/.env

# 4. set ADMIN_UP in apps/backend/.env to your NMEC to seed yourself as admin

# 5. generate the contract, create tables, load catalog + demo data
cd apps/backend
bun run contract:emit
bun run db:init
bun run db:seed:demo
cd ../..

⚠️ db:seed and db:seed:demo truncate every table. db:init only works on an empty database. Never run either against a shared database.

Run both servers

In two terminals:

cd apps/backend  && bun run dev   # http://localhost:3000
cd apps/frontend && bun run dev   # http://localhost:3100

Service	URL	Notes
Frontend	http://localhost:3100	Vite, HMR
Backend	http://localhost:3000	Elysia; routes under /v1
API docs	http://localhost:3000/openapi	Scalar, dev only
PostgreSQL	127.0.0.1:5434	Docker volume pgdata

Open http://localhost:3100. GET /health should answer { "status": "ok" }.

Daily loop

docker compose up -d --wait      # if not running
cd apps/backend  && bun run dev
cd apps/frontend && bun run dev

Common commands:

Task	Command (from apps/backend)
Regenerate contract after a schema edit	bun run contract:emit
Quick local schema sync	bun run db:update
Reset catalog + demo data	bun run db:seed:demo
Run backend tests	bun run test
Typecheck + contract emit	bun run typecheck
Inspect a failed migration	bun run migrate:show

From the root: bun run lint, bun run format, bun run format:check.

What “working” looks like

• http://localhost:3100 loads the planner/about pages.
• The login button works in dev (username/password), or you can seed yourself as admin.
• http://localhost:3000/health returns ok.
• http://localhost:3000/openapi renders in dev.
• The catalog is non-empty (run db:seed:demo, then check /v1/faculties while signed in).

Where the config lives

Do not copy the full env matrix into your head:

• full variable reference → Environments;
• committed schemas → apps/backend/.env.schema, apps/frontend/.env.schema;
• local values → the git-ignored .env files;
• auth details → Auth in development;
• first-run failures → Troubleshooting.

Useful extras

# frontend production build served by nginx on :3100
cd apps/frontend && ./build.sh prod && ./prod.sh

# database shell
docker compose exec postgres psql -U tts -d tts

# wipe the local database volume (destroys local data)
docker compose down -v && docker compose up -d --wait

Next

• Reading paths — the guide for your role
• Auth in development — dev login, roles and OIDC
• Contributing guide — branch, commits, PRs

---

Last verified: 2026-11-02