Skip to content

SETUP_GUIDE.md

Latest commit

 

History

History
371 lines (272 loc) · 7.71 KB

SETUP_GUIDE.md

File metadata and controls

371 lines (272 loc) · 7.71 KB

🚀 Setup Guide - Online Quiz System

This guide will help you set up and run the Online Quiz System on your local machine.

📋 Prerequisites

Before you begin, ensure you have the following installed:

Required Software

  1. Java Development Kit (JDK) 17 or higher

  2. Apache Maven 3.6 or higher

  3. Git (optional, for version control)

Recommended Software

  • IDE: IntelliJ IDEA, Eclipse, or VS Code
  • Terminal: PowerShell, Command Prompt, or Git Bash
  • Web Browser: Chrome, Firefox, or Edge

🔧 Installation Steps

Step 1: Navigate to Project Directory

cd "e:\MCQ spring"

Step 2: Build the Project

mvn clean install

This command will:

  • Download all dependencies
  • Compile the source code
  • Run tests (if any)
  • Package the application into a JAR file

Expected Output:

[INFO] BUILD SUCCESS
[INFO] Total time: XX.XXX s

Step 3: Verify Build

Check if the JAR file was created:

dir target\online-quiz-system-1.0.0.jar

🎮 Running the Application

Option 1: Run with Maven (Recommended for Development)

Start the Server:

mvn spring-boot:run

The server will start and display:

===========================================
Quiz Server Started on Port: 5000
Waiting for clients to connect...
===========================================

Option 2: Run JAR File Directly

Start the Server:

java -jar target\online-quiz-system-1.0.0.jar

Accessing the Web Interface

  1. Open your web browser
  2. Navigate to: http://localhost:8080
  3. You should see the Quiz System dashboard

👥 Running Multiple Clients

You need at least 2 clients to start a quiz.

Windows

Open multiple Command Prompt/PowerShell windows:

Terminal 1 (Client 1):

cd "e:\MCQ spring"
java -cp target\online-quiz-system-1.0.0.jar com.quiz.client.QuizClient

Terminal 2 (Client 2):

cd "e:\MCQ spring"
java -cp target\online-quiz-system-1.0.0.jar com.quiz.client.QuizClient

Terminal 3 (Client 3) - Optional:

cd "e:\MCQ spring"
java -cp target\online-quiz-system-1.0.0.jar com.quiz.client.QuizClient

Linux/Mac

Open multiple terminal windows:

cd "e:/MCQ spring"
java -cp target/online-quiz-system-1.0.0.jar com.quiz.client.QuizClient

🎯 Quick Start Guide

Complete Workflow

  1. Start the Server

    mvn spring-boot:run

    Wait for: "Quiz Server Started on Port: 5000"

  2. Open Web Dashboard (Optional)

  3. Start Client 1

    java -cp target\online-quiz-system-1.0.0.jar com.quiz.client.QuizClient
    • Enter name when prompted

  4. Start Client 2

    java -cp target\online-quiz-system-1.0.0.jar com.quiz.client.QuizClient
    • Enter name when prompted

  5. Quiz Starts Automatically

    • Server detects 2+ players and begins
    • Answer questions as they appear

  6. View Results

    • Final scores displayed in console
    • UDP broadcast received by all clients
    • Web dashboard shows leaderboard

🔍 Verification Checklist

After setup, verify the following:

  • Server starts without errors
  • Web interface loads at http://localhost:8080
  • Server status shows "RUNNING"
  • TCP Port shows 5000
  • UDP Port shows 5001
  • Clients can connect successfully
  • Questions are displayed correctly
  • Scores update properly
  • Final results are broadcast via UDP

🐛 Troubleshooting

Problem: "Port already in use"

Solution:

# Windows - Find process using port 8080
netstat -ano | findstr :8080
taskkill /PID <process_id> /F

# Find process using port 5000
netstat -ano | findstr :5000
taskkill /PID <process_id> /F

Problem: "Java command not found"

Solution:

  • Verify Java is installed: java -version
  • Add Java to PATH environment variable
  • Restart terminal after installation

Problem: "Maven command not found"

Solution:

  • Verify Maven is installed: mvn -version
  • Add Maven to PATH environment variable
  • Restart terminal after installation

Problem: "Connection refused" when client connects

Solution:

  • Ensure server is running
  • Check if firewall is blocking ports 5000/5001
  • Verify server address in QuizClient.java (should be "localhost")

Problem: "Build failed" during mvn install

Solution:

# Clean and rebuild
mvn clean
mvn install -U

# Skip tests if needed
mvn clean install -DskipTests

Problem: UDP broadcast not received

Solution:

  • Check network configuration
  • Disable firewall temporarily for testing
  • Ensure UDP port 5001 is not blocked
  • Try running all clients on localhost

📝 Configuration Changes

Change Server Ports

Edit src/main/resources/application.properties:

# HTTP Server Port
server.port=8080

# TCP Socket Port
quiz.server.tcp.port=5000

# UDP Broadcast Port
quiz.server.udp.port=5001

# Maximum Clients
quiz.server.max.clients=10

Change Client Connection

Edit src/main/java/com/quiz/client/QuizClient.java:

private static final String SERVER_HOST = "localhost";
private static final int SERVER_PORT = 5000;
private static final int UDP_PORT = 5001;

After changes, rebuild:

mvn clean install

🧪 Testing the Setup

Test 1: Server Health Check

curl http://localhost:8080/api/quiz/info

Expected Response:

{
  "tcpPort": 5000,
  "udpPort": 5001,
  "status": "running",
  "activePlayers": 0
}

Test 2: Leaderboard API

curl http://localhost:8080/api/quiz/leaderboard

Expected Response:

[]

(Empty array when no players)

Test 3: Full Quiz Flow

  1. Start server
  2. Connect 2 clients
  3. Complete quiz
  4. Verify final results in all consoles

📚 Additional Resources

  • README.md - Full project documentation
  • Source Code - Well-commented code in src/main/java/com/quiz/
  • Web UI - Interactive dashboard at http://localhost:8080

💡 Tips for Development

  1. Use IDE for easier development

    • Import as Maven project
    • Use built-in run configurations

  2. Enable hot reload

    • Spring Boot DevTools is included
    • Changes auto-reload during development

  3. View logs

    • Server logs show all activity
    • Client logs show connection status

  4. Test with multiple terminals

    • Use split terminal in VS Code
    • Or use Windows Terminal with multiple tabs

🎓 For Demonstration

When presenting to your instructor:

  1. Show Architecture Diagram (in README.md)

  2. Demonstrate Each Concept:

    • TCP Socket: Show connection establishment
    • Multithreading: Show multiple clients connecting
    • Synchronization: Show score updates
    • UDP: Show broadcast reception
    • Client-Server: Show message exchange

  3. Show Code Highlights:

    • Point out synchronized methods
    • Show thread pool creation
    • Demonstrate UDP broadcasting

  4. Run Live Demo:

    • Start server
    • Connect 3-5 clients
    • Complete a quiz
    • Show final results

✅ Success Criteria

Your setup is successful when:

✅ Server starts without errors
✅ Web dashboard is accessible
✅ Multiple clients can connect
✅ Quiz runs smoothly
✅ Scores are tracked correctly
✅ UDP broadcast is received
✅ All network concepts are demonstrated

Need Help? Check the troubleshooting section or contact your team members!