labFusion/docs/SONARQUBE_INTEGRATION.md

SonarQube Integration for LabFusion

This document explains how to configure SonarQube integration for all LabFusion services using individual projects per service.

Overview

Each LabFusion service has its own dedicated SonarQube project, providing better isolation, clearer metrics per service, and easier maintenance. This approach allows for service-specific quality gates and more granular reporting.

Required Configuration

1. SonarQube Secrets

You need to configure the following secrets in your Gitea repository:

• SONAR_HOST_URL: Your SonarQube server URL (e.g., http://localhost:9000 or https://sonar.yourdomain.com)
• SONAR_TOKEN: Your SonarQube authentication token

2. SonarQube Project Setup

1. Create individual projects in SonarQube for each service:

   • API Gateway: labfusion-api-gateway - "LabFusion API Gateway"
   • Service Adapters: labfusion-service-adapters - "LabFusion Service Adapters"
   • API Docs: labfusion-api-docs - "LabFusion API Docs"
   • Frontend: labfusion-frontend - "LabFusion Frontend"
   • Main Branch: main for all projects

2. Generate an authentication token:

   • Go to User > My Account > Security
   • Generate a new token with appropriate permissions
   • Copy the token for use in SONAR_TOKEN secret

3. SonarQube Quality Gates

Configure quality gates in SonarQube to enforce:

• Minimum code coverage percentage
• Maximum code duplication percentage
• Maximum technical debt ratio
• Code smell thresholds

What Gets Sent to SonarQube

Individual Service Projects

API Gateway

• Project Key: labfusion-api-gateway
• Project Name: LabFusion API Gateway
• Language: Java Spring Boot
• Test Reports: JUnit XML from target/surefire-reports/
• Coverage: JaCoCo XML from target/site/jacoco/jacoco.xml

Service Adapters

• Project Key: labfusion-service-adapters
• Project Name: LabFusion Service Adapters
• Language: Python FastAPI
• Test Reports: pytest XML from tests/reports/junit.xml
• Coverage: Coverage XML from coverage.xml

API Docs

• Project Key: labfusion-api-docs
• Project Name: LabFusion API Docs
• Language: Node.js Express
• Test Reports: Jest XML from test-results.xml
• Coverage: LCOV from coverage/lcov.info

Frontend

• Project Key: labfusion-frontend
• Project Name: LabFusion Frontend
• Language: React
• Test Reports: Jest XML from test-results.xml
• Coverage: LCOV from coverage/lcov.info

Code Quality Metrics

• Source code analysis results per service
• Code smells and issues per service
• Security vulnerabilities detection per service
• Maintainability ratings per service
• Service-specific quality gates and thresholds

Pipeline Integration

Individual Service Projects

Each service workflow sends results to its own dedicated SonarQube project:

API Gateway (Java)

- name: Send test results to SonarQube
  run: |
    ./mvnw clean verify sonar:sonar \
      -Dsonar.projectKey=labfusion-api-gateway \
      -Dsonar.projectName=LabFusion API Gateway \
      -Dsonar.host.url=${{ secrets.SONAR_HOST_URL }} \
      -Dsonar.token=${{ secrets.SONAR_TOKEN }}

Service Adapters (Python)

- name: Send results to SonarQube
  run: |
    sonar-scanner \
      -Dsonar.projectKey=labfusion-service-adapters \
      -Dsonar.projectName=LabFusion Service Adapters \
      -Dsonar.host.url=${{ secrets.SONAR_HOST_URL }} \
      -Dsonar.login=${{ secrets.SONAR_TOKEN }}

API Docs (Node.js)

- name: Send results to SonarQube
  run: |
    sonar-scanner \
      -Dsonar.projectKey=labfusion-api-docs \
      -Dsonar.projectName=LabFusion API Docs \
      -Dsonar.host.url=${{ secrets.SONAR_HOST_URL }} \
      -Dsonar.login=${{ secrets.SONAR_TOKEN }}

Frontend (React)

- name: Send results to SonarQube
  run: |
    sonar-scanner \
      -Dsonar.projectKey=labfusion-frontend \
      -Dsonar.projectName=LabFusion Frontend \
      -Dsonar.host.url=${{ secrets.SONAR_HOST_URL }} \
      -Dsonar.login=${{ secrets.SONAR_TOKEN }}

Maven Plugins Added

SonarQube Maven Plugin

<plugin>
    <groupId>org.sonarsource.scanner.maven</groupId>
    <artifactId>sonar-maven-plugin</artifactId>
    <version>3.10.0.2594</version>
</plugin>

JaCoCo Maven Plugin

<plugin>
    <groupId>org.jacoco</groupId>
    <artifactId>jacoco-maven-plugin</artifactId>
    <version>0.8.11</version>
    <!-- Configured for test phase execution -->
</plugin>

SonarQube Properties

Each service generates its own sonar-project.properties with module-specific settings:

API Gateway

sonar.projectKey=labfusion
sonar.projectName=LabFusion
sonar.projectVersion=1.0.0
sonar.modules=api-gateway
sonar.sources=src/main/java
sonar.tests=src/test/java
sonar.java.binaries=target/classes
sonar.java.test.binaries=target/test-classes
sonar.junit.reportPaths=target/surefire-reports
sonar.coverage.jacoco.xmlReportPaths=target/site/jacoco/jacoco.xml

Service Adapters

sonar.projectKey=labfusion
sonar.projectName=LabFusion
sonar.projectVersion=1.0.0
sonar.modules=service-adapters
sonar.sources=.
sonar.tests=tests
sonar.python.coverage.reportPaths=coverage.xml
sonar.python.xunit.reportPath=tests/reports/junit.xml

API Docs & Frontend

sonar.projectKey=labfusion
sonar.projectName=LabFusion
sonar.projectVersion=1.0.0
sonar.modules=api-docs
sonar.sources=.
sonar.tests=__tests__
sonar.javascript.lcov.reportPaths=coverage/lcov.info
sonar.testExecutionReportPaths=test-results.xml

Benefits

1. Service Isolation

• Each service has its own quality metrics
• Service-specific quality gates and thresholds
• Independent quality tracking per service
• Clear ownership and responsibility

2. Granular Reporting

• Service-specific test coverage reports
• Individual code smell identification
• Per-service security vulnerability detection
• Service-level technical debt tracking

3. Flexible Quality Gates

• Different quality standards per service type
• Language-specific quality rules
• Service-specific maintenance windows
• Independent quality gate configurations

4. Better Organization

• Clear separation of concerns
• Easier to identify problematic services
• Service-specific team assignments
• Independent service evolution

5. Integration Benefits

• No external service dependencies
• Local data control
• Customizable quality rules per service
• Team collaboration features per service

Troubleshooting

Common Issues

1. Authentication Failed

   • Verify SONAR_TOKEN is correct
   • Check token permissions in SonarQube
   • Ensure token hasn't expired

2. Connection Refused

   • Verify SONAR_HOST_URL is accessible
   • Check network connectivity
   • Ensure SonarQube is running

3. Project Not Found

   • Create project in SonarQube first
   • Verify project key matches configuration
   • Check project permissions

4. No Test Results

   • Ensure test files exist in src/test/java/
   • Verify Maven Surefire plugin configuration
   • Check test execution logs

Debug Commands

# Test SonarQube connection
curl -u $SONAR_TOKEN: $SONAR_HOST_URL/api/system/status

# Check project exists
curl -u $SONAR_TOKEN: $SONAR_HOST_URL/api/projects/search?q=labfusion-api-gateway

# Verify test reports exist
ls -la target/surefire-reports/
ls -la target/site/jacoco/

Next Steps

1. Configure SonarQube secrets in your Gitea repository
2. Set up quality gates in SonarQube
3. Run the pipeline to test integration
4. Review results in SonarQube dashboard
5. Customize quality rules as needed

References

• SonarQube Documentation
• SonarQube Maven Plugin
• JaCoCo Maven Plugin