Quick Start: Getting QLMS Up and Running

---

This guide will help you quickly set up and run the QLMS project, covering both Docker-based deployment and direct command-line execution.

---

Table of Contents

• 1. Quick Start with Docker (Recommended)
  • Prerequisites for Docker
  • Steps to Run with Docker
• 2. Quick Start Using Command-Line (Manual Setup)
  • Prerequisites for Command-Line
  • Steps to Run from Command-Line
    • 2.1. Run the Backend Application
    • 2.2. Run the Frontend Application
    • 2.3. Access the Application

---

1. Quick Start with Docker (Recommended)

Using Docker is the simplest way to get QLMS running as it handles all dependencies and environment setup.

Prerequisites for Docker

• Docker Desktop (or Docker Engine) installed and running on your system.
• Git installed and running on your system.

Steps to Run with Docker

1. Clone the Repository:

   First, get the QLMS project onto your local machine.

   git clone https://gitlab.com/akryadav/qlms.git

2. Navigate to the project root directory:

   Change your directory to the qlms folder, which contains both backend and frontend folders.

   cd qlms

3. Configure Email Settings (Important for Backend Functionality):

   Open the application.properties file located at qlms/backend/src/main/resources/application.properties and add the following email configuration:

   # Spring Mail Properties
   spring.mail.host=[host url of mail server]
   spring.mail.port=587
   spring.mail.username=[your-mail@gmail.com]
   spring.mail.password=[your app-password]
   spring.mail.properties.mail.smtp.auth=true
   spring.mail.properties.mail.smtp.starttls.enable=true

   Note: The spring.mail.password value should be a Gmail App Password if you have 2-Step Verification enabled on your Google account. Using your regular Gmail password directly is not recommended.

4. Build the Docker Images:

   This command will build both the backend and frontend Docker images. It might take a few minutes the first time, depending on your internet connection and system specifications.

   docker compose build

5. Start the QLMS Services:

   This will start the backend, frontend, and any necessary database services defined in your docker-compose.yml.

   docker compose up

   • The backend API will be accessible at http://localhost:8080.
   • The frontend application will be accessible at http://localhost:5173.

6. Access the Application:

   Open your web browser and go to http://localhost:5173 to access the QLMS frontend.

7. Stop the Services:

   When you're done, you can stop all running Docker containers with:

   docker compose down

---

2. Quick Start Using Command-Line (Manual Setup)

If you prefer to run the applications directly without Docker, follow these steps. You'll need to set up the environments for both the backend and frontend separately.

Prerequisites for Command-Line

• Java Development Kit (JDK) 17 or higher: Ensure JAVA_HOME is set correctly.
• Gradle: While the gradlew wrapper is included, having Gradle installed globally can be useful.
• Node.js (LTS version recommended): Install from nodejs.org.
• npm or Yarn: These come with Node.js.
• Database: You'll need a running PostgreSQL database.
• Git installed and running on your system.

Steps to Run from Command-Line

1. Clone the Repository:

   If you haven't already, clone the QLMS project:

   git clone https://gitlab.com/akryadav/qlms.git

2.1. Run the Backend Application

1. Navigate to the backend directory:

   cd qlms/backend

2. Configure Email Settings (Important for Backend Functionality):

   Open the application.properties file located at qlms/backend/src/main/resources/application.properties and add the following email configuration:

   # Spring Mail Properties
   spring.mail.host=[host url of mail server]
   spring.mail.port=587
   spring.mail.username=[your-mail@gmail.com]
   spring.mail.password=[your app-password]
   spring.mail.properties.mail.smtp.auth=true
   spring.mail.properties.mail.smtp.starttls.enable=true

   Note: The spring.mail.password value should be a Gmail App Password if you have 2-Step Verification enabled on your Google account. Using your regular Gmail password directly is not recommended.

3. Create a database and a user: You'll need a PostgreSQL database. Here's how to create one and a user for it:

   CREATE DATABASE qlms_db;
   CREATE USER [qlms_user] WITH PASSWORD '[password]';
   GRANT ALL PRIVILEGES ON DATABASE qlms_db TO [qlms_user];

   After creating the database and user, add the following properties to your qlms/backend/src/main/resources/application.properties file to configure the database connection:

   spring.datasource.username=[qlms_user]
   spring.datasource.password=[password]

4. Build the Backend Project:

   This command compiles the Java code and packages it into a JAR file.

   ./gradlew build

5. Start the Backend API Server:

   This will launch the Spring Boot application.

   java -jar build/libs/api-0.0.1-SNAPSHOT.jar

   The backend API will typically start on http://localhost:8080. You'll see logs indicating the application startup.

2.2. Run the Frontend Application

Open a new terminal window (keep the backend running in the first one).

1. Navigate to the frontend directory:

   cd qlms/frontend

2. Install Frontend Dependencies:

   This step only needs to be done once, or if package.json changes.

   npm install
   # or if you use Yarn:
   yarn install

3. Start the Frontend Development Server:

   This will compile and serve the React application.

   npm run dev
   # or if you use Yarn:
   yarn dev

   The frontend application will usually be accessible at http://localhost:5173.

2.3. Access the Application

Once both the backend and frontend are running, open your web browser and navigate to http://localhost:5173 to interact with the QLMS application.