Getting Started

Prerequisites#

Check Your Installed Versions#

Open a terminal and run the four commands below. If any command is “not recognized”, that software is not installed (or not on your PATH) — install it from the official link in the table above, then reopen the terminal.

node --version     # → v20.x.x or newer
npm --version     # comes with Node
pnpm --version    # if missing, install via Corepack (below)
git --version

Install pnpm (pick your OS)#

# Windows (PowerShell)
npm install -g pnpm

# macOS / Linux — Corepack ships with Node 16+
corepack enable
corepack prepare pnpm@latest --activate

# verify
pnpm --version

npm works too (npm install / npm run dev), but pnpm is what the maintainer used — disk-efficient and faster. All documentation commands use pnpm.

Install Dependencies (both projects)#

1. 1

   Backend dependencies

   Run Git Bash/PowerShell, cd into the backend folder and install. This downloads Express, Mongoose, and testing tools — expect 1–2 minutes.

   cd backend
   pnpm install

2. 2

   Frontend dependencies

   Open a second terminal for the frontend folder and install. This downloads Next.js 16, Tailwind CSS 4, Redux Toolkit and UI libraries.

   cd frontend
   pnpm install

First Run#

1. 1

   Start the backend (port 5000)

   cd backend
   pnpm dev
   # → Server running in development mode on port 5000
   # → API available at http://localhost:5000/api/v1

   If the backend exits immediately with “Config validation error: …”, the startup checks failed — the missing backend/.env variables are named in that message. See Environment Variables next.

2. 2

   Start the frontend (port 3000)

   cd frontend
   pnpm dev
   # → Local: http://localhost:3000

   Keep both terminals open. nodemon (backend) and Next.js (frontend) watch your files and reload automatically on changes.

Verify Everything Works#

The health endpoint lives under the API prefix. This is the single most reliable way to confirm the backend is fully up (config loaded + database connected).

curl http://localhost:5000/api/v1/health

# → {"success":true,"message":"Server is healthy","timestamp":"...","uptime":...}

Then open http://localhost:3000, register a test account and log in. The dashboard appears after login.

Register a test account from the frontend, then log in — the dashboard view opening without errors confirms the cookie-based session, the database and the frontend API proxy are all working.

Create the Admin Account#

backend/seed-admin.js reads ADMIN_EMAIL, ADMIN_PASSWORD and ADMIN_NAME from backend/.env (they are optional — there are built-in defaults, so ALWAYS set them yourself, see the authentication guide). It creates the admin user, or upgrades an existing user with that email to the admin role.

cd backend
node seed-admin.js

# Best practice — set these in backend/.env first:
# ADMIN_EMAIL=you@yourdomain.com
# ADMIN_PASSWORD=<a strong password of your choosing>
# ADMIN_NAME=Admin

Diagnosing First-Run Errors#

Anything not covered above has a dedicated page: Troubleshooting covers every setup-phase error the maintainer verified while building this kit.