Skip to content

Quick Start

Get the full ICOSYS platform running locally in three steps: database, backend services, and React frontend.

Prerequisites

Make sure you have completed the Installation guide first.

Architecture Overview

Browser (:5174)
   │
   ├─ /icglb/services/* ──► Icglb-Services  (:8010) ──► MySQL icglb2
   ├─ /icbpm/services/* ──► BPM-Services     (:8020) ──► MySQL icbpm
   └─ /icdms/services/* ──► DMS-Service      (:8030) ──► MySQL icdms

The Vite dev server proxies all /ic*/services/* requests to the corresponding backend port. You never need to configure CORS manually during development.

Step 1 — Database Setup

1.1 Start MySQL

Ensure MySQL 8.0 is running on port 3306.

# Verify MySQL is running
mysql -u root -p -e "SELECT VERSION();"
# Expected: 8.0.x

1.2 Create Schemas

Run once
CREATE DATABASE IF NOT EXISTS icglb2
  CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

CREATE DATABASE IF NOT EXISTS icbpm
  CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

CREATE DATABASE IF NOT EXISTS icdms
  CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

1.3 Run DDL Scripts

Each service module contains DDL scripts that must be executed before first startup.

Module DDL Location
Icglb-Services Icglb-Services-1.0/docs/database/ddl_scripts.md
BPM ICoSys-BPM/ICoSys-BPM-Entities-1.0/docs/database/ddl_scripts.md
DMS ICoSys-DMS-Service-1.0/ICoSys-DMS-Entities-1.0/docs/database/ddl_scripts.md

Order Matters

Run Icglb DDL first — BPM and DMS have foreign keys to icglb2 tables (e.g., cr_process, user_process).

Step 2 — Backend Services

2.1 Install Shared Libraries

Shared library JARs must be in your local Maven repository before any service can compile.

Install shared libraries (run once, from project root)
cd ICOM-Api-4.0          && mvn clean install -DskipTests && cd ..
cd ICOM-Services-Api-1.0 && mvn clean install -DskipTests && cd ..
cd Icglb-Entities-1.0    && mvn clean install -DskipTests && cd ..
cd Icglb-Entities-Dto-1.0 && mvn clean install -DskipTests && cd ..
cd ICOM-Micro-Services-Api-1.0 && mvn clean install -DskipTests && cd ..

2.2 Set Environment Variables

$env:DB_PASSWORD = "your_mysql_password"

export DB_PASSWORD="your_mysql_password"

2.3 Start Icglb-Services (Core)

Terminal 1
cd Icglb-Services-1.0
mvn spring-boot:run -Dspring-boot.run.profiles=dev

Wait for the log line:

Started IcglbServicesApplication in X.XXs — port 8010

Verify:

curl http://localhost:8010/icglb/services/actuator/health
# Expected: {"status":"UP"}

2.4 Start BPM Service

Terminal 2
cd ICoSys-BPM/ICoSys-BPM-Services-1.0
mvn spring-boot:run -Dspring-boot.run.profiles=dev

Wait for startup on port 8020.

2.5 Start DMS Service

Terminal 3
cd ICoSys-DMS-Service-1.0/ICoSys-DMS-Service-1.0
mvn spring-boot:run -Dspring-boot.run.profiles=dev

Wait for startup on port 8030.

Service Startup Order

Services are independent — you can start them in any order. However, the React frontend requires at least Icglb-Services to be running for login to work.

Service Summary

Service Port Health Check
Icglb-Services 8010 http://localhost:8010/icglb/services/actuator/health
BPM-Services 8020 http://localhost:8020/icbpm/services/actuator/health
DMS-Service 8030 http://localhost:8030/icdms/services/actuator/health

Step 3 — React Frontend

3.1 Install Dependencies

Terminal 4
cd ICoSys-Web-React-1.0
npm install

3.2 Start Dev Server

npm run dev

The Vite dev server starts on http://localhost:5174 with hot module replacement.

  VITE v7.3.1  ready in 300ms

  ➜  Local:   http://localhost:5174/

3.3 Open the App

Navigate to http://localhost:5174 in your browser. Log in with your credentials — the login page authenticates against Icglb-Services.

Proxy Configuration

The Vite dev server routes API requests to backend services automatically:

vite.config.ts (excerpt)
server: {
  port: 5174,
  proxy: {
    '/icglb/services': 'http://localhost:8010',
    '/icbpm/services': 'http://localhost:8020',
    '/icdms/services': 'http://localhost:8030',
  }
}

No CORS in Development

Because Vite proxies all API calls, the browser sees a same-origin request. Backend CORS settings are only relevant for test/production environments.

Useful Commands

Frontend

Command Description
npm run dev Start Vite dev server with HMR
npm run build Production build to dist/
npx tsc --noEmit TypeScript type checking (no output)
npm run lint ESLint check
npm run test Run Vitest unit tests
npm run test:coverage Run tests with coverage report

Backend

Command Description
mvn spring-boot:run -Dspring-boot.run.profiles=dev Start service with dev profile
mvn clean install -DskipTests Build and install to local repo
mvn test Run unit tests
mvn clean verify sonar:sonar -DskipTests SonarQube analysis

Troubleshooting

Port already in use

If a port is occupied, find and stop the process:

netstat -ano | findstr :8010
taskkill /PID <pid> /F

lsof -i :8010
kill -9 <pid>
MySQL connection refused
  • Verify MySQL is running: mysql -u root -p -e "SELECT 1;"
  • Check that DB_PASSWORD environment variable is set
  • Ensure the schemas exist: SHOW DATABASES;
Maven build fails — dependency not found

Shared libraries must be installed first. Re-run the commands in Step 2.1 and retry.

Frontend shows blank page or 502
  • Check that Icglb-Services is running on port 8010
  • Open browser DevTools → Network tab to see failing requests
  • Verify Vite proxy config matches running service ports

What's Next?