Skip to content

Installation

This guide covers all prerequisites and tools required to develop and run the ICOSYS platform locally.

Prerequisites at a Glance

Tool Minimum Version Purpose
Java JDK 21 Backend compilation and runtime
Maven 3.9+ Backend build and dependency management
Node.js 18+ Frontend toolchain runtime
npm 9+ Frontend package management
MySQL 8.0 Relational database
Git 2.40+ Version control

1. Java 21

The backend services target Java 21 LTS with preview features disabled.

Download and install Eclipse Temurin 21 or Oracle JDK 21.

Set the environment variable:

PowerShell
[Environment]::SetEnvironmentVariable("JAVA_HOME", "C:\Program Files\Eclipse Adoptium\jdk-21", "User")
Homebrew
brew install --cask temurin@21
SDKMAN (recommended)
sdk install java 21-tem

Verify:

java -version
# Expected: openjdk version "21.x.x"

2. Apache Maven

Maven builds all backend modules. Version 3.9+ is required for Java 21 support.

Download the binary zip from maven.apache.org, extract to C:\tools\maven, and add C:\tools\maven\bin to your PATH.

brew install maven

sdk install maven

Verify:

mvn -version
# Expected: Apache Maven 3.9.x+ and Java 21

Maven Wrapper

Each backend module includes mvnw / mvnw.cmd. You can use ./mvnw instead of a global Maven installation.

3. Node.js & npm

The React frontend requires Node.js 18+ (LTS recommended).

Download the LTS installer from nodejs.org or use nvm-windows:

nvm install lts
nvm use lts
nvm (recommended)
nvm install --lts
nvm use --lts

Verify:

node -v   # Expected: v18.x or higher
npm -v    # Expected: 9.x or higher

4. MySQL 8.0

All backend services connect to MySQL 8.0 with per-module schemas.

Download MySQL Installer and run the full install. Keep the default port 3306.

brew install mysql@8.0
brew services start mysql@8.0
Quick start with Docker
docker run -d \
  --name icosys-mysql \
  -e MYSQL_ROOT_PASSWORD=root \
  -p 3306:3306 \
  mysql:8.0

Create Schemas

Connect to MySQL as root and create the three required schemas:

Schema setup
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;
Schema Service Description
icglb2 Icglb-Services Core platform — auth, users, accounts, config
icbpm ICoSys-BPM-Services Business Partner Management
icdms ICoSys-DMS-Service Document Management System

Hibernate DDL Mode

All services use spring.jpa.hibernate.ddl-auto=validate. Hibernate will not create tables automatically. You must run the DDL scripts found in each module's docs/database/ddl_scripts.md before first startup.

5. Git

Any recent Git version works. 2.40+ recommended for performance.

git -v
# Expected: git version 2.40+
IDE Best For Plugins
IntelliJ IDEA Backend (Java/Spring) Lombok, Spring Boot
VS Code Frontend (React/TS) ESLint, Tailwind CSS IntelliSense, Prettier

Lombok Setup

IntelliJ IDEA requires the Lombok plugin and annotation processing enabled: Settings → Build → Compiler → Annotation Processors → Enable.

7. Environment Variables

Backend services read secrets from environment variables with dev-safe defaults. For local development, only DB_PASSWORD is strictly required.

Variable Required Default (dev) Description
DB_USERNAME No root MySQL username
DB_PASSWORD Yes — MySQL password
JWT_SECRET No 64-char hex dev key JWT signing secret (HS512)
ICGLB_SECURITY_API_KEY No Dev fallback key Inter-service API key
DMS_URL_SECRET No Dev fallback key DMS signed URL secret
ENCRYPTION_KEY No — AES key for encrypted fields (DMS only)
Set for current session
$env:DB_PASSWORD = "your_mysql_password"
Add to ~/.bashrc or ~/.zshrc
export DB_PASSWORD="your_mysql_password"

Production Secrets

Never use the default dev keys in production. Generate secure random values:

openssl rand -hex 32   # For JWT_SECRET, API keys
openssl rand -hex 16   # For ENCRYPTION_KEY (32 chars)

8. Directory Layout

Clone or ensure the following repositories exist under a common parent directory:

projectRoot/
├── Icglb-Services-1.0/                # Core backend service
├── ICoSys-BPM/                        # BPM module (multi-module Maven)
│   ├── ICoSys-BPM-Types-1.0/
│   ├── ICoSys-BPM-Entities-1.0/
│   ├── ICoSys-BPM-Entities-Dto-1.0/
│   └── ICoSys-BPM-Services-1.0/
├── ICoSys-DMS-Service-1.0/            # DMS module (multi-module Maven)
│   ├── ICoSys-DMS-Types-1.0/
│   ├── ICoSys-DMS-Entities-1.0/
│   ├── ICoSys-DMS-Entities-Dto-1.0/
│   └── ICoSys-DMS-Service-1.0/
├── ICOM-Micro-Services-Api-1.0/       # Shared service API library
├── ICOM-Services-Api-1.0/             # CrudService interfaces
├── ICOM-Api-4.0/                      # Core API interfaces
├── Icglb-Entities-1.0/                # Core entities
├── Icglb-Entities-Dto-1.0/            # Core DTOs
└── ICoSys-Web-React-1.0/              # React frontend

Shared Libraries

ICOM-Micro-Services-Api-1.0, ICOM-Services-Api-1.0, ICOM-Api-4.0, Icglb-Entities-1.0, and Icglb-Entities-Dto-1.0 must be installed to your local Maven repository (mvn install) before building any service module.

Technology Stack — Full Reference

Backend

Technology Version What Why License
Java 21 LTS Language and runtime Long-term support, virtual threads, pattern matching GPL-2.0 w/ CPE
Spring Boot 3.5.6 Application framework Auto-configuration, embedded server, production-ready Apache-2.0
Spring Security 6.x Auth framework JWT validation, RBAC, CORS, rate limiting Apache-2.0
Spring Data JPA 3.x Data access layer Repository pattern, Specification queries Apache-2.0
Hibernate 6.x ORM JPA implementation, schema validation LGPL-2.1
MySQL Connector/J 8.x JDBC driver MySQL 8 protocol support GPL-2.0
HikariCP 5.x Connection pool Fastest JDBC pool, zero-overhead Apache-2.0
JJWT 0.12.5 JWT library Token creation, parsing, HS512 signing Apache-2.0
Bucket4j 8.10.1 Rate limiting Token-bucket algorithm, per-IP throttling Apache-2.0
Jackson 2.18.0 JSON processing Serialization/deserialization Apache-2.0
Lombok 1.18.32 Code generation Reduce boilerplate (getters, builders, constructors) MIT
SLF4J 2.0.16 Logging facade Unified logging API across all modules MIT
Apache PDFBox 3.0.4 PDF processing Text extraction for DMS indexing Apache-2.0
Apache POI 5.3.0 Office documents DOCX/XLSX content extraction for DMS Apache-2.0
Maven 3.9+ Build tool Dependency management, multi-module builds Apache-2.0

Frontend

Technology Version What Why License
React 19.2.0 UI library Component-based SPA framework MIT
TypeScript 5.9.3 Language Type safety, IDE support, refactoring confidence Apache-2.0
Vite 7.3.1 Build tool Fast HMR, ESM-native dev server, optimized builds MIT
Tailwind CSS 4.1.18 CSS framework Utility-first styling, dark mode, responsive design MIT
shadcn/ui — UI components Accessible, composable Radix-based components MIT
TanStack Table 8.21.3 Data table Headless table with sorting, filtering, pagination MIT
Zustand 5.0.11 State management Lightweight, no boilerplate, devtools support MIT
React Hook Form 7.71.1 Form handling Performant forms with minimal re-renders MIT
Zod 4.3.6 Schema validation TypeScript-first validation with type inference MIT
Axios 1.13.5 HTTP client Interceptors, error handling, request cancellation MIT
React Router 7.13.0 Routing Client-side navigation, nested routes MIT
Lucide React 0.563.0 Icons Consistent icon set, tree-shakeable ISC
Sonner 2.0.7 Toast notifications Accessible, stackable toast system MIT
Vitest 4.0.18 Test runner Vite-native unit testing, fast execution MIT
ESLint 9.39.1 Linter Code quality, consistent patterns MIT

Infrastructure

Technology Version What Why License
MySQL 8.0 Database ACID compliance, JSON support, window functions GPL-2.0
GitHub Actions — CI/CD Automated lint, type-check, test, build, SonarQube —
SonarQube — Code quality Static analysis, coverage tracking, Grade A compliance LGPL-3.0

What's Next?

  • Quick Start — Run the entire platform locally in 10 minutes
  • First Module — Create your first backend module from scratch