ツール  /  SonarQube

SonarQube — Docker による導入・実行・確認

Docker Compose を使って SonarQube をローカル・CI 環境に素早く立ち上げる方法を解説します。 Quality Gate / Quality Profile の設定基準から SonarScanner の実行、解析結果の読み方・対応手順まで一貫して学べます。

「SonarQube」は、現場で実際に必要に迫られて取り組んだ作業をまとめたものです。断片的な情報しかなく、試行錯誤しながら完成させた手順をそのまま記録しています。

1. SonarQube とは

SonarQube分析フロー図

図1: SonarQube分析フロー — ソースコードから品質レポート生成まで

SonarQube は、ソースコードの静的解析を行うオープンソースのコード品質管理プラットフォームです。 バグ・セキュリティ脆弱性・コードスメル(技術的負債)・カバレッジを一元管理し、 継続的インテグレーション(CI)パイプラインに組み込むことでコード品質の維持・向上を支援します。

エディション特徴利用場面
Community Edition 無償。主要言語の静的解析。ブランチ解析は main のみ。 個人・小規模チーム・学習目的
Developer Edition 有償。Pull Request 解析・ブランチ解析対応。 CI/CD に組み込む開発チーム
Enterprise / Data Center ポートフォリオ管理・高可用性構成。 大規模組織・エンタープライズ

2. 前提条件

項目要件
DockerDocker Desktop 4.x 以上(Docker Engine 24+)
Docker Composev2 以上(docker compose コマンド形式)
メモリホスト RAM 4 GB 以上推奨(SonarQube は JVM ヒープを 512 MB 以上使用)
vm.max_map_countLinux ホストの場合 262144 以上が必要(Elasticsearch 要件)
⚠️ Linux ホストの場合は事前設定が必要
sudo sysctl -w vm.max_map_count=262144 を実行してください。 永続化する場合は /etc/sysctl.conf に vm.max_map_count=262144 を追記します。

3. 導入方法 — Docker Compose セットアップ

SonarQube と PostgreSQL を Docker Compose で起動します。 データの永続化にはボリュームを使用します。

ディレクトリ構成

bash
mkdir sonarqube-docker && cd sonarqube-docker

docker-compose.yml

YAML — docker-compose.yml
services:
  sonarqube:
    image: sonarqube:10-community        # Community Edition(最新 LTS を推奨)
    container_name: sonarqube
    depends_on:
      - db
    environment:
      SONAR_JDBC_URL: jdbc:postgresql://db:5432/sonar
      SONAR_JDBC_USERNAME: sonar
      SONAR_JDBC_PASSWORD: sonar
    volumes:
      - sonarqube_data:/opt/sonarqube/data
      - sonarqube_extensions:/opt/sonarqube/extensions
      - sonarqube_logs:/opt/sonarqube/logs
    ports:
      - "9000:9000"
    restart: unless-stopped

  db:
    image: postgres:15
    container_name: sonarqube_db
    environment:
      POSTGRES_USER: sonar
      POSTGRES_PASSWORD: sonar
      POSTGRES_DB: sonar
    volumes:
      - postgresql_data:/var/lib/postgresql/data
    restart: unless-stopped

volumes:
  sonarqube_data:
  sonarqube_extensions:
  sonarqube_logs:
  postgresql_data:

起動と初期ログイン

  1. コンテナを起動する
    bash
    docker compose up -d
    
    # 起動ログを確認(SonarQube の起動には 1〜2 分かかる)
    docker compose logs -f sonarqube
  2. ブラウザでアクセス
    http://localhost:9000 を開き、 初期ユーザー admin / パスワード admin でログインします。 ログイン後、パスワード変更を求められるので必ず変更してください。
  3. プロジェクトを作成する
    ログイン後、「Create a local project」を選択し、プロジェクトキー・表示名を入力します。
  4. トークンを発行する
    「Generate a token」で解析用トークンを発行し、メモしておきます(後でScannerに使用)。
✅ コンテナの停止・再起動
docker compose stop で停止、docker compose start で再起動できます。 ボリュームを削除しない限りデータは保持されます。

4. 実行基準 — Quality Gate / Quality Profile

Quality Profile

Quality Profile は、言語ごとに適用する静的解析ルールセットです。 デフォルトは Sonar way(SonarSource 推奨ルールセット)が設定されています。

設定項目説明操作場所
プロファイルの選択 「Sonar way」を基本に、必要に応じてカスタムプロファイルを作成する。 Administration → Quality Profiles
ルールの有効化 / 無効化 プロジェクト要件に合わせて個別ルールを on/off する。 Quality Profiles → ルール一覧
重要度の変更 ルールごとに BLOCKER / CRITICAL / MAJOR / MINOR / INFO を設定。 Quality Profiles → ルール詳細

Quality Gate

Quality Gate は、解析結果がパス / 失敗を判定する閾値の定義です。 CI/CD パイプラインではこの判定を使ってデプロイの可否を制御します。

デフォルト条件(Sonar way)閾値説明
新規コードのバグ 0件 今回の変更で追加されたバグが0件であること。
新規コードの脆弱性 0件 今回の変更で追加されたセキュリティ脆弱性が0件であること。
新規コードのセキュリティホットスポット 100% レビュー済み 要確認のホットスポットが全てレビューされていること。
新規コードのコードカバレッジ 80% 以上 新規コードのテストカバレッジが80%以上であること。
新規コードの重複率 3% 以下 新規コードの重複コード率が3%以下であること。
💡 カスタム Quality Gate の作成
Administration → Quality Gates で「Create」から新規ゲートを作成できます。 チームの成熟度に合わせて最初は緩やかな閾値から始め、段階的に引き上げるのが推奨です。

5. 実行方法 — SonarScanner の実行

Docker 内の SonarQube に対して、SonarScanner(別途インストール)でコードを送信・解析します。 SonarScanner も Docker で実行できます。

sonar-project.properties の作成

プロジェクトルートに sonar-project.properties を配置します。

properties — sonar-project.properties
# プロジェクトの識別子(SonarQube UI で設定したキーと一致させる)
sonar.projectKey=my-project
sonar.projectName=My Project
sonar.projectVersion=1.0

# ソースコードのパス(複数指定はカンマ区切り)
sonar.sources=src/main/java
sonar.tests=src/test/java

# Java の場合:コンパイル済みクラスファイルのパス
sonar.java.binaries=target/classes

# テストカバレッジレポート(JaCoCo を使用する場合)
sonar.coverage.jacoco.xmlReportPaths=target/site/jacoco/jacoco.xml

# 文字コード
sonar.sourceEncoding=UTF-8

Docker で SonarScanner を実行

bash
# プロジェクトルートで実行
docker run --rm \
  --network host \
  -e SONAR_HOST_URL="http://localhost:9000" \
  -e SONAR_TOKEN="<発行したトークン>" \
  -v "$(pwd):/usr/src" \
  sonarsource/sonar-scanner-cli:latest
💡 Windows(PowerShell)での実行
$(pwd) の代わりに ${PWD} を使用してください。

JaCoCo カバレッジの事前取得(Java / Maven の場合)

bash
# Maven でテスト実行 + JaCoCo レポート生成
mvn clean verify

# 上記完了後に SonarScanner を実行
docker run --rm \
  --network host \
  -e SONAR_HOST_URL="http://localhost:9000" \
  -e SONAR_TOKEN="<発行したトークン>" \
  -v "$(pwd):/usr/src" \
  sonarsource/sonar-scanner-cli:latest

6. 実行後の確認

解析完了後、SonarQube UI(http://localhost:9000)でプロジェクトを開き、以下の観点で結果を確認します。

Quality Gate ステータスの確認

プロジェクトの概要画面上部に Passed(緑)または Failed(赤)が表示されます。 Failed の場合は、どの条件で失敗しているかを確認します。

問題の深刻度(Severity)

深刻度意味対応優先度
BLOCKER 即時修正が必要なバグ・クラッシュ要因。本番デプロイ前に必ず対処。 最高
CRITICAL データ損失・セキュリティ侵害につながる重大問題。 高
MAJOR 機能障害・パフォーマンス問題を起こしうる欠陥。 中
MINOR コードの可読性・保守性に影響するが機能には影響しない問題。 低
INFO 情報提供のみ。参考として確認。 最低

確認すべき主要メトリクス

メトリクス確認ポイント
Bugs NullPointerException・リソースリーク・誤った比較など、確実にバグとなるコード。
Vulnerabilities SQLインジェクション・XSS・ハードコードされた認証情報などのセキュリティ問題。
Security Hotspots 脆弱性の可能性があるコード。レビューして安全と判断したらマーク。
Code Smells 技術的負債。命名規則・複雑度・重複コードなど保守性に関する問題。
Coverage テストカバレッジ。新規コードに対して80%以上を目標とする。
Duplications コードの重複率。3%以下が Quality Gate のデフォルト基準。

7. 確認後の対応

Issues の対応フロー

  1. BLOCKER / CRITICAL を優先対処
    Issues 画面でSeverity = BLOCKER / CRITICAL に絞り込み、該当行のコードを修正します。 SonarQube は修正方法(Why is this an issue?)と例を提示するので参考にします。
  2. 誤検知(False Positive)のマーク
    意図的なコードや誤検知と判断した Issue は「Won't Fix」または「False Positive」にマークします。 理由をコメントとして記録しておくと後のレビューで役立ちます。
  3. Security Hotspots のレビュー
    Hotspot を1件ずつ確認し、脆弱性がなければ「Safe」にマーク、問題があれば「To fix」にして修正します。
  4. 修正後に再解析して結果を確認
    コードを修正後、再度 SonarScanner を実行し、Quality Gate が Passed になることを確認します。

運用上のポイント

観点推奨対応
CI/CD への組み込み GitHub Actions / Jenkins 等のパイプラインに SonarScanner を組み込み、PR ごとに自動解析を実施する。
Quality Gate の段階的強化 最初は既存のコードスメルを除外し、新規コードのみ Quality Gate を適用する「New Code」モードから始める。
定期的なレポート確認 週次・スプリント単位で技術的負債の推移を確認し、リファクタリング計画に反映する。
除外設定 自動生成コードや外部ライブラリは sonar.exclusions で解析対象から除外する。
properties — 除外設定例(sonar-project.properties)
# 解析対象から除外するパターン(自動生成コード・外部ライブラリなど)
sonar.exclusions=**/generated/**,**/vendor/**,**/*Test.java

# テストカバレッジの除外(エンティティクラス・設定クラスなど)
sonar.coverage.exclusions=**/entity/**,**/config/**,**/dto/**

8. まとめ

フェーズ内容ポイント
導入Docker Compose で SonarQube + PostgreSQL を起動ボリュームでデータ永続化。Linux は vm.max_map_count に注意。
基準設定Quality Profile / Quality Gate の確認・調整「Sonar way」をベースにチームのルールを追加。
実行sonar-project.properties 配置 → SonarScanner 実行カバレッジは JaCoCo で事前生成してから解析。
確認Quality Gate ステータス・Bugs / Vulnerabilities / Coverage を確認BLOCKER / CRITICAL を最優先で対処。
対応修正 → 再解析 → Passed を確認誤検知は Won't Fix / False Positive でマーク。

参考・公式ドキュメント