Skip to main content

​
Overview

This guide walks you through setting up the Extracurricular Management System (EMS) for local development. EMS uses a Spring Boot backend with MySQL and a React frontend with Vite.

​
Prerequisites

Before you begin, ensure you have the following installed:

Backend Requirements

  • Java 21 (JDK)
  • Apache Maven 3.6+
  • MySQL 8.0+

Frontend Requirements

  • Node.js 20+
  • npm (comes with Node.js)

​
Verify Prerequisites

Run these commands to verify your installations:
Terminal
# Check Java version
java -version  # Should show Java 21

# Check Maven version
mvn -version

# Check MySQL
mysql --version

# Check Node.js and npm
node --version  # Should be 20+
npm --version

​
Database Setup

1

Start MySQL Server

Ensure your MySQL server is running:
# Linux/Mac
sudo systemctl start mysql

# Or check if it's already running
sudo systemctl status mysql
2

Create Database User

Create a dedicated database user for the application:
CREATE USER 'app_user'@'localhost' IDENTIFIED BY 'your_secure_password';
GRANT ALL PRIVILEGES ON ems_db.* TO 'app_user'@'localhost';
FLUSH PRIVILEGES;
The database ems_db will be created automatically by the application on first run due to the createDatabaseIfNotExist=true parameter.
3

Verify Database Access

Test the connection:
mysql -u app_user -p -e "SHOW DATABASES;"

​
Backend Setup

1

Navigate to Backend Directory

cd backend
2

Configure Application Properties

Create or edit backend/src/main/resources/application.properties:
application.properties
# Server Configuration
server.port=8080

# 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 (Matching JwtUtils.java)
secreteJwtString=404E635266556A586E3272357538782F413F4428472B4B6250645367566B5970
expirationInt=86400000

# Email Configuration (Development - Mailtrap)
spring.mail.host=sandbox.smtp.mailtrap.io
spring.mail.port=2525
spring.mail.username=YOUR_MAILTRAP_USERNAME
spring.mail.password=YOUR_MAILTRAP_PASSWORD
spring.mail.properties.mail.smtp.auth=true
spring.mail.properties.mail.smtp.starttls.enable=true
Replace YOUR_PASSWORD with your MySQL user password and configure SMTP settings. See the Configuration page for detailed options.
3

Install Dependencies

Maven will automatically download all dependencies:
mvn clean install
This command compiles the code and runs any available tests.
4

Start the Backend Server

Run the Spring Boot application:
mvn spring-boot:run
The backend will start on http://localhost:8080. You should see:
Started EmsBackendApplication in X.XXX seconds
5

Verify Backend is Running

Test the API endpoint:
curl http://localhost:8080/api/health

​
Frontend Setup

1

Navigate to Frontend Directory

cd frontend/ems-frontend
2

Create Environment File

Create a .env file in the frontend directory:
.env
VITE_API_BASE_URL=http://localhost:8080/api
This tells the frontend where to find the backend API.
3

Install Dependencies

Install all Node.js packages:
npm install
This installs React 19, TanStack Query v5, Tailwind CSS v4, and other dependencies.
4

Start the Development Server

Run the Vite development server:
npm run dev
The frontend will start on http://localhost:5173 (or the next available port).
5

Access the Application

Open your browser and navigate to the URL shown in the terminal (typically http://localhost:5173).

​
Project Structure

Understanding the codebase layout: 
backend/
├── src/main/java/com/ems/backend/
│   ├── controller/      # REST API endpoints
│   ├── service/         # Business logic layer
│   ├── repository/      # Data access layer
│   ├── entity/          # JPA entities
│   ├── dto/             # Data transfer objects
│   ├── security/        # JWT and security config
│   ├── enums/           # Enumeration types
│   └── exception/       # Exception handling
├── src/main/resources/
│   └── application.properties
└── pom.xml              # Maven dependencies

​
Development Workflow

​
Running Both Servers

For full-stack development, run both servers in separate terminals: 
cd backend
mvn spring-boot:run

​
Hot Reloading

  • Backend: Spring Boot DevTools enables automatic restart on code changes
  • Frontend: Vite provides instant hot module replacement (HMR)

​
Building for Production

cd backend
mvn clean package
# Creates target/ems-backend-0.0.1-SNAPSHOT.jar

​
Troubleshooting

Problem: Communications link failure or connection refused errors.Solutions:
  • Verify MySQL is running: sudo systemctl status mysql
  • Check MySQL is listening on port 3306: sudo netstat -tlnp | grep 3306
  • Verify credentials in application.properties
  • Try connecting manually: mysql -u app_user -p
Problem: Port 8080 is already in use or Port 5173 is already in use.Solutions:
  • Kill the process using the port: lsof -ti:8080 | xargs kill -9
  • Change the port in configuration files:
    • Backend: Modify server.port in application.properties
    • Frontend: Vite will automatically use the next available port
Problem: Authentication fails with token errors.Solutions:
  • Ensure secreteJwtString in application.properties matches the value in JwtUtils.java (backend/src/main/java/com/ems/backend/security/JwtUtils.java:26)
  • The secret must be at least 256 bits (32+ characters)
  • Clear browser local storage and log in again
Problem: Email notifications fail to send.Solutions:
  • For development, use Mailtrap instead of real SMTP
  • Verify SMTP credentials are correct
  • Check firewall isn’t blocking port 587 or 2525
  • Test with a simple SMTP client
Problem: mvn clean install fails with dependency errors.Solutions:
  • Update Maven: mvn --version should be 3.6+
  • Clear Maven cache: rm -rf ~/.m2/repository
  • Run with -U flag: mvn clean install -U
  • Check your Java version is exactly 21
Problem: Cannot find module errors when running frontend.Solutions:
  • Delete node_modules and reinstall: rm -rf node_modules && npm install
  • Clear npm cache: npm cache clean --force
  • Verify Node.js version is 20+: node --version
  • Check for package.json corruption

​
Next Steps

Configuration

Learn about all configuration options and environment variables

Deployment

Deploy your application to production

Architecture

Understand the system architecture

API Reference

Explore the REST API endpoints

​
Development Tips

Use Mailtrap for Email Testing: During development, use Mailtrap to capture all outgoing emails without sending them to real addresses.
Database Schema Evolution: The application uses spring.jpa.hibernate.ddl-auto=update which automatically evolves the database schema. In production, use validate and manage migrations explicitly.
API Testing: Use tools like Postman or Bruno to test API endpoints independently of the frontend.

Build docs developers (and LLMs) love

Get started for freeTalk to us