Local Setup

This guide walks you through running the full NextGenPoll stack on your local machine.

---

Step 1 — Clone the Repository

git clone https://github.com/NextGenPoll/NextGenPoll.git
cd NextGenPoll

---

Step 2 — Configure Environment Variables

Both backend and frontend read from a shared .env file at the monorepo root.

cp .env.example .env

Open .env and fill in your values. For local development, most defaults work without changes. The variables you will likely need to set are:

• AZURE_TENANT_ID — your Azure CIAM tenant ID (for auth)
• NEXT_PUBLIC_AZURE_CLIENT_ID — your app registration client ID
• AZURE_OPENAI_API_KEY — for AI summary features (optional)

See Environment Variables for the complete reference.

Local overrides

• Backend: Create backend/.env to override root .env (Spring reads the local file first).
• Frontend: Create frontend/.env.local to override root .env (Next.js convention).

---

Step 3 — Start the Database

docker compose up -d

This starts PostgreSQL 18 on localhost:5432 with:

Setting	Value
Database	nextgenpoll
Username	ngp_user
Password	ngp_local_pass

Confirm it is running:

docker compose ps
# Expected: db   running   0.0.0.0:5432->5432/tcp

---

Step 4 — Install Node.js Dependencies

# Run from the monorepo root — installs frontend, powerpoint, docs, and shared packages
npm ci

Always install from the root

This project uses npm workspaces. There is a single package-lock.json at the root. Running npm install inside a subdirectory will create a nested package-lock.json and cause version conflicts.

---

Step 5 — Start the Backend

# Windows
cd backend
mvnw.cmd clean spring-boot:run

# Mac / Linux
cd backend
./mvnw clean spring-boot:run

On first run, Flyway automatically:

1. Creates all database tables.
2. Seeds initial data (response types, a default admin user).

Verify the backend is running:

curl http://localhost:8080/api/health
# Expected: {"status":"UP","service":"nextgenpoll-api"}

API documentation is available at http://localhost:8080/ (auto-redirects to Scalar UI).

---

Step 6 — Start the Frontend

Open a new terminal tab:

cd frontend
npm run dev

The frontend runs at http://localhost:3000.

---

Step 7 — (Optional) Start the PowerPoint Add-in

Open another terminal tab:

cd powerpoint

# Windows only — install dev certificate (once)
npx office-addin-dev-certs install

npm start

The add-in dev server runs at https://localhost:4000. See PowerPoint Add-in for sideloading instructions per OS.

---

Step 8 — (Optional) Start the Docs Site

npm run start --workspace=docs

The docs dev server runs at http://localhost:3030.

---

Verify Everything Works

Service	URL	Expected
Backend health	http://localhost:8080/api/health	{"status":"UP","service":"nextgenpoll-api"}
API docs	http://localhost:8080/	Scalar UI (auto-redirect)
Polls list	http://localhost:8080/api/polls	JSON poll list
Frontend	http://localhost:3000	Home page
Join page	http://localhost:3000/join	Enter RANKIT to test Ranking + Choice
Dashboard	http://localhost:3000/dashboard	Dashboard (requires login)

---

Stopping Services

# Stop the database (keeps data)
docker compose stop

# Stop the database and delete all data
docker compose down -v

# Stop frontend / backend — press Ctrl+C in each terminal

---

Re-running Migrations Manually

If you reset the database (docker compose down -v), restart the backend to re-apply all migrations. To run migrations without starting the backend:

# Windows
cd backend
mvnw.cmd flyway:migrate

# Mac / Linux
cd backend
./mvnw flyway:migrate