推測はやめてスキャンを始めよう：HomeLabにDockerでSonarQubeをデプロイする方法

Table of Contents

HomeLabプロジェクトの隠れた負担：技術的負債

多くのHomeLabは、シンプルなJellyfinのインストールやHome Assistantのダッシュボードから始まります。しかし、あなたが開発者であれば、そのサーバーはすぐにカスタムスクリプトや自動化ワークフローの実験場となるでしょう。バックアップ管理用のPythonスクリプト、カスタムダッシュボード用のJavaScriptスニペット、あるいは軽量なAPI用のGoバイナリなどを書くことになるかもしれません。

最初はすべてが完璧に動作します。しかし、プロジェクトが成長するにつれて、壁に突き当たることになります。半年前に書いたスクリプトを開くと、意味のわからない300行の「if-else」チェーンに直面したり、さらに悪いことに、公開スクリプトの中に誤ってAPIキーをハードコードしていたことに気づいたりするかもしれません。これが「技術的負債」です。プロフェッショナルな現場では、シニア開発者がレビューを行ってくれますが、HomeLabでは通常、非効率なコードや安全でないコードを指摘してくれる人はおらず、自分一人で進めるしかありません。

なぜ個人プロジェクトは劣化するのか

個人プロジェクトのコード品質が低下するのは、フィードバックループが存在しないからです。「コードの不吉な臭い（Code Smells）」、つまり深い設計上の欠陥を示唆するパターンを指摘するシステムがなければ、何かが壊れたときに初めて問題に気づくことになります。手動でのリンティング（Linting）は退屈な作業です。新しい機能を動かすことに夢中になっているとき、私たちの多くはそれをスキップしてしまいます。

さまざまな本番環境での運用経験から、自動化された静的アプリケーションセキュリティテスト（SAST）ツールの導入こそが、唯一の信頼できる解決策であると確信しています。SonarQubeはそのための業界標準のツールです。これは仮想的なシニア開発者のように機能し、コードのすべての行をスキャンして、何を修正すべきかの明確なロードマップを提示してくれます。

クイックスタート：5分で始めるSonarQube

SonarQubeを動かすためにDocker Composeを使用します。SonarQubeにはテスト用の組み込みデータベースが含まれていますが、初日からPostgreSQLを使用することを強くお勧めします。これにより、コンテナのアップデートや再起動を行っても解析履歴が保持されます。

1. ホストシステムの準備

SonarQubeは内部でElasticsearchインスタンスを使用します。デフォルトでは、ほとんどのLinuxカーネルのメモリマップエリアの上限が低く設定されており、これが原因でSonarQubeが起動直後にクラッシュすることがあります。ホストマシンでこの制限を引き上げる必要があります：

sudo sysctl -w vm.max_map_count=262144

この変更を永続的にするには、/etc/sysctl.confファイルにvm.max_map_count=262144を追加してください。

2. Docker Composeファイル

sonarqubeという名前のディレクトリを作成し、その中に以下のdocker-compose.ymlを保存します：

version: '3.8'

services:
  db:
    image: postgres:15-alpine
    container_name: sonarqube_db
    networks:
      - sonarnet
    environment:
      - POSTGRES_USER=sonar
      - POSTGRES_PASSWORD=sonar_password
      - POSTGRES_DB=sonarqube
    volumes:
      - postgresql_data:/var/lib/postgresql/data

  sonarqube:
    image: sonarqube:community
    container_name: sonarqube_app
    depends_on:
      - db
    networks:
      - sonarnet
    ports:
      - "9000:9000"
    environment:
      - SONAR_JDBC_URL=jdbc:postgresql://db:5432/sonarqube
      - SONAR_JDBC_USERNAME=sonar
      - SONAR_JDBC_PASSWORD=sonar_password
    volumes:
      - sonarqube_data:/opt/sonarqube/data
      - sonarqube_extensions:/opt/sonarqube/extensions
      - sonarqube_logs:/opt/sonarqube/logs

networks:
  sonarnet:

volumes:
  postgresql_data:
  sonarqube_data:
  sonarqube_extensions:
  sonarqube_logs:

docker-compose up -dで起動します。サービスが初期化されるまで約2分待ちます。その後、http://<your-ip>:9000でダッシュボードにアクセスできます。デフォルトの認証情報admin / adminでログインしてください。システムからすぐにパスワードの変更を求められます。

ディープダイブ：SonarQubeの仕組み

ダッシュボードが稼働したら、そのアーキテクチャを理解する必要があります。SonarQubeは単にフォルダを監視するバックグラウンドサービスではなく、クライアント・サーバーモデルを採用しています。

サーバー vs スキャナー

デプロイしたサーバーは「頭脳」にあたります。ルールを保存し、データベースを管理し、ウェブインターフェースを表示します。しかし、サーバー自体が直接ファイルを読み取るわけではありません。そのために必要なのが、Sonar Scannerです。

Scannerは軽量なCLIツールです。これを開発マシンやCI/CDパイプライン内で実行します。ローカルでソースコードを解析し、メトリクスを計算して、最終的なレポートをAPI経由でサーバーに送信します。

メトリクスの理解

バグ (Bugs): 明らかなエラーです。未処理のヌルポインタや、定義前に使用された変数などを指します。
脆弱性 (Vulnerabilities): セキュリティ上の欠陥です。SonarQubeはSQLインジェクションのリスクや脆弱な暗号化アルゴリズムの使用などを検出します。
コードの不吉な臭い (Code Smells): 保守性の問題です。コードは動作しますが、乱雑な状態です。例えば、500行もある関数や、10階層のネストなどが該当します。
技術的負債 (Technical Debt): 時間の推定値です。特定されたすべての問題をクリーンアップするために、具体的に何時間、あるいは何日かかるかを示します。

高度な使い方：最初のスキャンを実行する

Pythonプロジェクトをスキャンしてみましょう。ローカルマシンにJavaやスキャナーをインストールする代わりに、一時的なDockerコンテナを使用して重い処理を行わせることができます。

1. セキュリティトークンの生成

SonarQube UIのMy Account > Securityに移動します。「HomeLab-Scanner」という名前で新しいトークンを生成します。二度と表示されないため、すぐにコピーしておいてください。

2. プロジェクトの設定

プロジェクトのルートディレクトリに、sonar-project.propertiesという名前のファイルを作成します：

sonar.projectKey=my-awesome-automation
sonar.projectName=私の素晴らしい自動化プロジェクト
sonar.projectVersion=1.0
sonar.sources=.
sonar.language=py
sonar.sourceEncoding=UTF-8

3. 解析の実行

プロジェクトのルートからこのコマンドを実行します（IPとトークンを更新してください）：

docker run --rm \
    -e SONAR_HOST_URL="http://192.168.1.50:9000" \
    -e SONAR_SCANNER_OPTS="-Dsonar.projectKey=my-awesome-automation" \
    -e SONAR_TOKEN="ここに生成したトークンを入力" \
    -v "$(pwd):/usr/src" \
    sonarsource/sonar-scanner-cli

スキャンが完了したらダッシュボードを更新してください。プロジェクトの健康診断レポートが表示されます。「クオリティゲート（Quality Gate）」機能は特に便利です。テストカバレッジ80%以上や新規セキュリティ欠陥ゼロといった基準を満たしているかどうかに基づいて、シンプルな「合格」または「不合格」のステータスを表示してくれます。

HomeLabを安定させるための実践的ヒント

SonarQubeはJavaアプリケーションであるため、リソースをかなり消費します。小型のNUCやRaspberry Pi 5で実行している場合は、制限を設ける必要があります。

メモリ消費の制限

RAMが4GBや8GBしかないマシンでは、SonarQubeがシステム全体を占有してしまう可能性があります。sonarqube環境設定セクションに以下の行を追加することで、メモリ使用量を制限できます：

- SONAR_SEARCH_JAVAOPTS=-Xmx512m -Xms512m
- SONAR_WEB_JAVAOPTS=-Xmx512m -Xms512m

Giteaによる自動化

GiteaのようなGitサーバーを運用している場合、Gitea Actionsを使用して、プッシュ（Push）のたびに自動的にスキャンを実行できます。これにより、プロフェッショナル級のワークフローが構築されます。コードをプッシュするとスキャンが開始され、フィードバックがUIに表示されます。これにより、問題を数ヶ月放置するのではなく、即座に修正する習慣が身につきます。

ストレージとログ

SonarQubeのログは急速に肥大化することがあります。Composeファイルでlogsボリュームをマッピングしているため、ホストシステムでlogrotateを設定し、ログを500MB以下に保つことをお勧めします。また、postgresql_dataのバックアップも忘れないでください。ソースコードはGitにあれば安全ですが、解析履歴やカスタムルールはすべてそのデータベースの中に存在しています。

SonarQubeを導入することは、「ただ動くものを作る」段階から、実際の「ソフトウェアエンジニアリング」への転換点となります。SonarQubeは、あなたのHomeLabプロジェクトが今後何年にもわたって安全で読みやすく、メンテナンス可能な状態であることを保証する、プロフェッショナルなセーフティネットを提供してくれます。