Skip to main content

​
Overview

This guide will help you set up the Extracurricular Management System (EMS) on your local machine. You’ll have both the backend API and frontend application running in under 15 minutes.

​
Prerequisites

Before you begin, ensure you have the following installed:

Java 21

Required for running the Spring Boot backend

Maven

Build tool for the Java backend

MySQL 8.0

Database server for storing application data

Node.js 20+

JavaScript runtime for the React frontend
You’ll also need an SMTP account (Gmail, Outlook, or Mailtrap) for email notifications.

​
Backend Setup

1

Set up MySQL Database

Create a database and user for EMS:
CREATE DATABASE ems_db;
CREATE USER 'app_user'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON ems_db.* TO 'app_user'@'localhost';
FLUSH PRIVILEGES;
2

Configure Application Properties

Navigate to backend/src/main/resources/ and configure application.properties:
application.properties
# Database Configuration
spring.datasource.url=jdbc:mysql://localhost:3306/ems_db?createDatabaseIfNotExist=true&useSSL=false&allowPublicKeyRetrieval=true
spring.datasource.username=app_user
spring.datasource.password=your_password
spring.jpa.hibernate.ddl-auto=update

# JWT Configuration
secreteJwtString=REPLACE_WITH_SECURE_HEX_STRING
expirationInt=86400000

# Email Configuration (Gmail example)
spring.mail.host=smtp.gmail.com
spring.mail.port=587
spring.mail.username[email protected]
spring.mail.password=your-app-password
spring.mail.properties.mail.smtp.auth=true
spring.mail.properties.mail.smtp.starttls.enable=true
Generate a secure random string for secreteJwtString. You can use an online hex generator or run: openssl rand -hex 32
3

Start the Backend

Run the Spring Boot application:
cd backend
mvn spring-boot:run
The backend API will start on http://localhost:8080

​
Frontend Setup

1

Configure Environment Variables

Create a .env file in frontend/ems-frontend/:
.env
VITE_API_BASE_URL=http://localhost:8080/api
2

Install Dependencies

Install npm packages:
cd frontend/ems-frontend
npm install
3

Start the Development Server

Run the Vite development server:
npm run dev
The frontend will be available at http://localhost:5173

​
Verify Installation

Visit http://localhost:8080/actuator/health in your browser. You should see:
{
  "status": "UP"
}
Use curl or Postman to register a test user:
curl -X POST http://localhost:8080/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Test",
    "lastName": "User",
    "email": "[email protected]",
    "password": "password123",
    "role": "STUDENT",
    "studentID": "S123456",
    "major": "Computer Science",
    "yearOfStudy": 3
  }'
You should receive a 201 Created response.
Open http://localhost:5173 in your browser. You should see the EMS login page.

​
Common Issues

Error: Cannot create PoolableConnectionFactorySolution:
  • Verify MySQL is running: mysql -u root -p
  • Check database credentials in application.properties
  • Ensure the database ems_db exists
Error: Port 8080 is already in useSolution:
  • Change the port in application.properties: server.port=8081
  • Or kill the process using port 8080
Error: CORS policy: No 'Access-Control-Allow-Origin' headerSolution:
  • Verify VITE_API_BASE_URL in frontend .env matches your backend URL
  • Check CORS configuration in backend CorsConfig.java
Error: Mail server connection failedSolution:
  • For Gmail: Enable 2FA and generate an app password
  • For Outlook: Use your regular password with smtp.office365.com
  • For development: Use Mailtrap.io for testing

​
Next Steps

Architecture

Learn about the system design and patterns

Configuration Guide

Explore advanced configuration options

API Documentation

Start building with the REST API

User Guides

Understand user workflows

​
Development Tips

Hot Reload: Both frontend (Vite) and backend (Spring DevTools) support hot reload during development. Changes will automatically reflect without restarting.
Database Schema: On first run, Hibernate will automatically create tables based on JPA entities. Check your database to verify schema creation.
Email Testing: For local development, use Mailtrap to test emails without sending real messages.

Build docs developers (and LLMs) love

Get started for freeTalk to us