POTE/docs/17_sonarqube_setup.md

# SonarQube Setup Guide for POTE

**Complete guide for setting up SonarQube code quality analysis.**

---

## 🎯 Overview

SonarQube provides:
- **Code Quality Metrics** - Maintainability, reliability, security
- **Technical Debt** - Time to fix issues
- **Code Coverage** - Test coverage visualization
- **Code Smells** - Code quality issues
- **Security Vulnerabilities** - Security hotspots
- **Bug Detection** - Potential bugs

---

## 📋 Prerequisites

### 1. SonarQube Server
- ✅ You mentioned you have the runner (SonarQube server)
- Server URL: `http://your-sonarqube-server:9000` (or your URL)
- Server must be accessible from CI/CD runners

### 2. SonarQube Project
- Project key: `pote` (configured in `sonar-project.properties`)
- Project name: `POTE`
- Can be created manually or auto-created on first scan

### 3. SonarQube Token
- User token with permissions:
  - ✅ **Execute Analysis** (required)
  - ✅ **Create Projects** (if project doesn't exist)

---

## 🔧 Step 1: Create SonarQube Project

### Option A: Create Manually (Recommended)

1. **Login to SonarQube:**
   ```
   http://your-sonarqube-server:9000
   ```

2. **Create Project:**
   - Go to: **Projects** → **Create Project**
   - **Project Key:** `pote`
   - **Display Name:** `POTE`
   - **Main Branch:** `main`
   - Click **Set Up**

3. **Generate Token:**
   - Go to: **My Account** → **Security** → **Generate Token**
   - **Name:** `POTE CI/CD`
   - **Type:** **User Token**
   - **Expires:** (set expiration or leave blank)
   - Click **Generate**
   - **⚠️ COPY THE TOKEN** - You won't see it again!

### Option B: Auto-Create (First Scan)

- Project will be created automatically on first scan
- Token must have **"Create Projects"** permission

---

## 🔐 Step 2: Configure Gitea Secrets

### Add Secrets in Gitea

1. **Go to Repository Settings:**
   ```
   https://git.levkin.ca/ilia/POTE/settings/secrets/actions
   ```

2. **Add Secret: `SONAR_HOST_URL`**
   - **Name:** `SONAR_HOST_URL`
   - **Value:** `http://your-sonarqube-server:9000`
   - Example: `http://10.0.30.169:9000`
   - Click **Add Secret**

3. **Add Secret: `SONAR_TOKEN`**
   - **Name:** `SONAR_TOKEN`
   - **Value:** (paste the token from Step 1)
   - Click **Add Secret**

### Verify Secrets

```bash
# In CI pipeline, secrets are available as:
${{ secrets.SONAR_HOST_URL }}
${{ secrets.SONAR_TOKEN }}
```

---

## 📄 Step 3: Project Configuration

### File: `sonar-project.properties`

Already created in project root with these settings:

```properties
# Project identification
sonar.projectKey=pote
sonar.projectName=POTE
sonar.projectVersion=0.1.0

# Source code location
sonar.sources=src
sonar.sourceEncoding=UTF-8

# Test code location
sonar.tests=tests
sonar.test.inclusions=**/test_*.py

# Exclusions
sonar.exclusions=**/__pycache__/**,**/*.pyc,**/venv/**,**/tests/**,**/alembic/versions/**

# Python-specific settings
sonar.python.version=3.11

# Coverage reports
sonar.python.coverage.reportPaths=coverage.xml
```

### Customize if Needed

Edit `sonar-project.properties` to:
- Change project key/name
- Add more exclusions
- Configure additional settings

---

## 🚀 Step 4: CI Pipeline Integration

### Already Configured!

The CI pipeline (`.github/workflows/ci.yml`) includes:

1. **SonarScanner Installation**
   - Downloads and installs SonarScanner CLI
   - Version: `5.0.1.3006` (stable)

2. **Coverage Report Generation**
   - Runs pytest with coverage
   - Generates `coverage.xml` for SonarQube

3. **SonarScanner Execution**
   - Runs analysis
   - Uploads results to SonarQube server
   - Non-blocking (won't fail CI if SonarQube is unavailable)

### Job: `sonar-analysis`

```yaml
sonar-analysis:
  runs-on: ubuntu-latest
  env:
    SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
    SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
  steps:
    - Install SonarScanner
    - Generate coverage report
    - Run SonarScanner analysis
```

---

## 🧪 Step 5: Test Locally (Optional)

### Install SonarScanner Locally

```bash
# Download SonarScanner
wget https://binaries.sonarsource.com/Distribution/sonar-scanner-cli/sonar-scanner-cli-5.0.1.3006-linux.zip
unzip sonar-scanner-cli-5.0.1.3006-linux.zip
export PATH=$PATH:$(pwd)/sonar-scanner-5.0.1.3006-linux/bin
```

### Run Analysis Locally

```bash
cd /home/user/Documents/code/pote

# Generate coverage report
source venv/bin/activate
pytest tests/ --cov=src/pote --cov-report=xml

# Run SonarScanner
sonar-scanner \
  -Dsonar.host.url=http://your-sonarqube-server:9000 \
  -Dsonar.token=your_token_here
```

### Or Use Environment Variables

```bash
export SONAR_HOST_URL=http://your-sonarqube-server:9000
export SONAR_TOKEN=your_token_here
sonar-scanner
```

---

## 📊 Step 6: View Results

### In SonarQube UI

1. **Go to Project:**
   ```
   http://your-sonarqube-server:9000/dashboard?id=pote
   ```

2. **View Metrics:**
   - **Overview** - Overall quality gate status
   - **Issues** - Bugs, vulnerabilities, code smells
   - **Measures** - Coverage, complexity, duplications
   - **Code** - Source code with inline issues
   - **Activity** - Analysis history

### Quality Gate

SonarQube will show:
- ✅ **Pass** - Meets quality standards
- ❌ **Fail** - Doesn't meet quality standards

### Common Metrics

- **Coverage** - Test coverage percentage
- **Duplications** - Code duplication percentage
- **Maintainability Rating** - A-E rating
- **Reliability Rating** - A-E rating
- **Security Rating** - A-E rating
- **Technical Debt** - Time to fix all issues

---

## 🔧 Configuration Options

### Quality Gate

Configure in SonarQube:
- **Projects** → **POTE** → **Quality Gates**
- Set thresholds for:
  - Coverage
  - Duplications
  - Bugs
  - Vulnerabilities
  - Code smells

### Exclusions

Add to `sonar-project.properties`:

```properties
# Exclude specific files
sonar.exclusions=**/legacy/**,**/old_code/**

# Exclude specific issues
sonar.issue.ignore.multicriteria=e1
sonar.issue.ignore.multicriteria.e1.ruleKey=python:S1234
sonar.issue.ignore.multicriteria.e1.resourceKey=**/*.py
```

### Coverage Exclusions

```properties
# Exclude from coverage
sonar.coverage.exclusions=**/tests/**,**/migrations/**,**/__init__.py
```

---

## 🐛 Troubleshooting

### Issue: "Project 'pote' does not exist"

**Solution:**
1. Create project manually in SonarQube UI
2. OR ensure token has "Create Projects" permission

### Issue: "Authentication failed"

**Solution:**
1. Verify `SONAR_TOKEN` secret is correct
2. Check token hasn't expired
3. Regenerate token if needed

### Issue: "Connection refused"

**Solution:**
1. Verify `SONAR_HOST_URL` is correct
2. Check SonarQube server is running
3. Verify network connectivity from CI runner
4. Check firewall rules

### Issue: "Coverage report not found"

**Solution:**
1. Ensure pytest runs before SonarScanner
2. Check `coverage.xml` is generated
3. Verify path in `sonar-project.properties`:
   ```properties
   sonar.python.coverage.reportPaths=coverage.xml
   ```

### Issue: "No files to analyze"

**Solution:**
1. Check `sonar.sources=src` is correct
2. Verify source files aren't excluded
3. Check file encoding (should be UTF-8)

---

## 📈 Best Practices

### 1. Regular Analysis
- Run on every commit (already configured in CI)
- Review results regularly
- Fix issues incrementally

### 2. Quality Gate
- Set realistic thresholds
- Start with warnings, not failures
- Gradually increase standards

### 3. Coverage
- Aim for 80%+ coverage
- Focus on critical paths first
- Don't sacrifice quality for coverage

### 4. Technical Debt
- Track and reduce over time
- Prioritize high-impact issues
- Set time limits for fixing

### 5. Team Integration
- Share SonarQube dashboard with team
- Review issues in code reviews
- Use quality gate in PR checks

---

## 🔗 Integration with CI/CD

### Current Setup

✅ **Already Integrated:**
- Runs automatically on every push
- Non-blocking (won't fail CI)
- Generates coverage report
- Uploads results to SonarQube

### Make Quality Gate Blocking (Optional)

To fail CI if quality gate fails:

```yaml
- name: Run SonarScanner
  run: |
    sonar-scanner \
      -Dsonar.qualitygate.wait=true \
      ...
```

Then remove `continue-on-error: true` from the step.

---

## 📝 Summary

### Quick Setup Checklist

- [ ] SonarQube server running and accessible
- [ ] Project `pote` created in SonarQube (or auto-create enabled)
- [ ] Token generated with "Execute Analysis" permission
- [ ] `SONAR_HOST_URL` secret added to Gitea
- [ ] `SONAR_TOKEN` secret added to Gitea
- [ ] `sonar-project.properties` file exists (✅ already created)
- [ ] CI pipeline includes `sonar-analysis` job (✅ already added)
- [ ] Test by pushing to dev branch

### Files Created

- ✅ `sonar-project.properties` - Project configuration
- ✅ `.github/workflows/ci.yml` - Updated with SonarScanner job

### Next Steps

1. **Add secrets to Gitea** (Step 2)
2. **Push to dev branch** - CI will run SonarScanner
3. **View results** in SonarQube dashboard
4. **Configure quality gate** as needed
5. **Review and fix issues** incrementally

---

## 📞 Support

- **SonarQube Docs:** https://docs.sonarqube.org/
- **SonarScanner Docs:** https://docs.sonarqube.org/latest/analysis/scan/sonarscanner/
- **Python Plugin:** https://docs.sonarqube.org/latest/analysis/languages/python/

---

**Last Updated:** December 2025  
**SonarScanner Version:** 5.0.1.3006  
**Python Version:** 3.11