Quick Start Guide This guide will help you get HERCULES SGI up and running quickly. Follow these steps to deploy a local development or production instance.
This quick start focuses on a Docker-based deployment for simplicity. For production deployments, refer to the deployment guide.
Prerequisites Before you begin, ensure you have the following installed:
Required Software
Java Development Kit 11+
HERCULES SGI backend services require Java 11 or later. We recommend using Eclipse Temurin (formerly AdoptOpenJDK). # Verify Java installation java -version # Should show version 11 or higher
The production Docker images use Eclipse Temurin 21 JRE Alpine for optimal performance.
PostgreSQL 12+
The system uses PostgreSQL as the primary database. Oracle and SQL Server are also supported. # Install PostgreSQL (example for Ubuntu/Debian) sudo apt-get install postgresql-12
Keycloak 11.0.0
Authentication and authorization are handled by Keycloak. # Download Keycloak 11.0.0 wget https://github.com/keycloak/keycloak/releases/download/11.0.0/keycloak-11.0.0.tar.gz tar -xzf keycloak-11.0.0.tar.gz
Node.js 12+ and npm
Required for building the Angular frontend application. # Verify Node.js installation node --version # Should be v12 or higher npm --version
Maven 3.6+
Required for building the Java backend services. # Verify Maven installation mvn --version # Should be 3.6 or higher
Quick Setup with Docker Make sure Docker and Docker Compose are installed and running on your system.
Step 1: Clone the Repository # Clone the HERCULES SGI repository git clone https://github.com/HerculesCRUE/SGI.git cd SGI
Start Keycloak
# Navigate to Keycloak directory cd keycloak-11.0.0/bin # Start Keycloak in standalone mode ./standalone.sh
Create SGI Realm
Access Keycloak Admin Console at http://localhost:8080/auth
Create a new realm named sgi
Configure the OAuth2 clients as specified in the configuration files
Configure OAuth2 Clients
Create the following clients in the sgi realm: Frontend Client (front) :Client ID : front Client Protocol : openid-connect Access Type : public Valid Redirect URIs : http://localhost:4200/*
Service Clients (for each microservice):Client ID : csp-service Client Protocol : openid-connect Access Type : confidential Service Accounts Enabled : true Authorization Enabled : true
Step 3: Build Backend Services # Build all backend services mvn clean install -DskipTests # Or build individual services cd sgi-csp-service mvn clean package -DskipTests
The build process creates executable JAR files in each service’s target/ directory.
Step 4: Prepare Docker Images # Extract dependencies for Docker layering (example for CSP service) cd sgi-csp-service mkdir -p target/dependency cd target/dependency jar -xf ../ * .jar # Build Docker image cd ../.. docker build -t sgi-csp-service:latest .
Each service includes a Dockerfile:
# Example: sgi-csp-service/Dockerfile FROM eclipse-temurin:21-jre-alpine EXPOSE 8080 COPY target/dependency/BOOT-INF/lib /app/lib COPY target/dependency/META-INF /app/META-INF COPY target/dependency/BOOT-INF/classes /app ENTRYPOINT java -Duser.timezone=UTC -Djava.security.egd=file:/dev/./urandom -cp "app:app/lib/*" org.crue.hercules.sgi.csp.CspApplication
Create Databases
Create separate databases for each service: -- PostgreSQL example CREATE DATABASE csp ; CREATE DATABASE eti ; CREATE DATABASE pii ; CREATE DATABASE prc ; CREATE DATABASE cnf ; CREATE DATABASE com ; CREATE DATABASE usr ; CREATE DATABASE rep ; CREATE DATABASE rel ; CREATE DATABASE eer ; CREATE DATABASE tp ; -- Create schemas CREATE SCHEMA IF NOT EXISTS csp; CREATE SCHEMA IF NOT EXISTS eti; -- ... repeat for each service
Update Configuration
Edit application.yml for each service to point to your database: spring : datasource : url : "jdbc:postgresql://postgres:5432/csp" driver-class-name : org.postgresql.Driver username : postgres password : your_password jpa : properties : hibernate : dialect : org.hibernate.dialect.PostgreSQL10Dialect '[default_schema]' : csp
Run Liquibase Migrations
The system uses Liquibase for database schema management. Migrations run automatically on first startup. spring : liquibase : enabled : true contexts : dev default-schema : csp
Step 6: Build and Start Frontend # Navigate to webapp directory cd sgi-webapp # Install dependencies npm install # Build the Angular framework ng build sgi-framework-angular # Start development server npm start
The web application will be available at http://localhost:4200.
The frontend build includes a custom CKEditor 5 build for rich text editing capabilities.
Step 7: Start Microservices Start each backend service individually or use a process manager:
# Start CSP Service (Grants, Applications & Projects) cd sgi-csp-service java -jar target/sgi-csp-service-1.1.0-SNAPSHOT.jar --spring.profiles.active=dev # Start ETI Service (Ethics) cd sgi-eti-service java -jar target/sgi-eti-service-1.1.0-SNAPSHOT.jar --spring.profiles.active=dev # Repeat for other services...
Ensure services start in the correct order. Configuration (CNF) and User (USR) services should start first as other services depend on them.
Default Ports Each service runs on a dedicated port:
Service Port Description sgi-webapp 4200 Angular frontend sgi-auth (Keycloak) 8080 Authentication service sgi-eti-service 4280 Ethics service sgi-csp-service 4281 Grants/Projects service sgi-tp-service 4285 Scheduled tasks service sgi-com-service 4286 Communications service sgi-rep-service 4287 Reporting service sgi-cnf-service 4288 Configuration service
First Login
Access the Application
Navigate to http://localhost:4200 in your web browser.
Keycloak Authentication
You’ll be redirected to the Keycloak login page at: http://localhost:8080/auth/realms/sgi/protocol/openid-connect/auth
Login with Credentials
Use the credentials configured in Keycloak for your initial admin user.
Explore the Dashboard
After successful authentication, you’ll see the main HERCULES SGI dashboard with access to:
Convocatorias (Funding Calls)
Proyectos (Projects)
Ética (Ethics Reviews)
Producción Científica (Scientific Production)
Propiedad Industrial (Intellectual Property)
Verify Installation Check that all services are running correctly:
# Check service health endpoints curl http://localhost:4281/actuator/health # CSP Service curl http://localhost:4280/actuator/health # ETI Service curl http://localhost:4288/actuator/health # CNF Service
Expected response:
Configuration Profiles HERCULES SGI supports multiple Spring profiles:
dev : Development mode with H2 database and debug loggingdev-oracle : Development with Oracle databasedev-sqlserver : Development with SQL Server databaseprod : Production mode with PostgreSQL
Activate profiles using:
java -jar service.jar --spring.profiles.active=prod
Next Steps
Architecture Overview Learn about the system architecture and microservices
Configuration Guide Configure the system for your institution
User Management Set up users, roles, and permissions
Core Modules Explore the core research management modules
Troubleshooting
Service fails to start with database connection error
Verify that PostgreSQL is running and accessible: psql -U postgres -h localhost -p 5432
Check the database URL in application.yml matches your PostgreSQL configuration.
Keycloak authentication fails
Ensure:
Keycloak is running on port 8080
The sgi realm is created
OAuth2 clients are properly configured
The issuer-uri in application.yml is correct
Frontend shows blank page
Check browser console for errors. Common issues:
Backend services not running
CORS configuration issues
Keycloak client configuration mismatch
Liquibase migration fails
If migrations fail, check: # View Liquibase logs tail -f logs/application.log | grep liquibase
Ensure the database user has schema creation privileges.