Prerequisites

Checklist

• Node.js installed (v18 or higher)
• pnpm installed
• PostgreSQL available (local or Docker)
• Git installed
• Docker installed (recommended)
• Access to repository

Local Setup

Checklist

• Repository cloned
• Dependencies installed

Environment & Configuration

Checklist

• Create .env.local from .env.example
• Fill required variables (DB, auth, app URL)
• Confirm config is loaded by the app
• Understand which values differ by environment (dev/staging/prod)

First Run

Checklist (Day-1 success)

• Local services running (DB/cache)

• Migrations applied (and seed data loaded if available)

• Dev server running

• You can log in

• A core workflow works end-to-end

• You made a small code change and saw hot reload

• Lint + tests pass

• Seed demo data (optional but recommended)

• Start the dev server

• Database migrated

• (Optional) Seed data loaded

Troubleshooting

Fast debug checklist

• Read the terminal output fully (first error is often the real one)
• Confirm .env.local exists and required vars are set
• Confirm Docker services are running (docker ps)
• Confirm DB connectivity (can you connect with a DB client?)
• Restart dev server after changing env vars
• Check ports (3000/5432/6379) are not in use
• Clear caches and rebuild when necessary