2025년 3월 17일

사용기 - 맥에서 도커 기반 SonarQube 활용하기

SonarQube는 코드에 대한 버그, 코드 스멜(Code Smell), 보안 취약점을 자동으로 찾아내고, 코드 품질을 향상시키는 데 도움을 주는 소스 코드 품질 및 보안 분석 도구이다.

버전에 따라 기능의 차이가 있는데 Community Edition (무료) 은  GitHub Private Repository 연동을 지원하지는 않지만 Git 에서 직접 코드를 가져와 분석할 수 있기 때문에 사용하는데 있어 큰 이슈는 없을 것 같다.

버전

특징

GitHub Private Repo 분석

Community Edition

무료, 기본적인 코드 분석 가능

✗ (직접 클론 후 분석)

Developer Edition

추가적인 언어 지원, 분기(branch) 분석

✓

Enterprise Edition

대규모 프로젝트 지원, 포트폴리오 관리

✓


◼︎ 환경

  • Model : MacBook Pro (14-inch, 2021)
  • CPU : Apple M1 Pro
  • MENORY : 16GB
  • DISK : 512 GB SSD
  • OS : macOS 15.3.1 (24D70)
  • TOOLS : VS Code , Docker

1. Docker 설치

Docker 는 공식 웹사이트에서 Docker Desktop for Mac을 다운로드하여 설치한다.


https://www.docker.com/products/docker-desktop

설치파일을 다운로드 후 Docker.dmg 파일을 클릭하여 설치를 진행할 수 있다. 설치가 완료되면 터미널에서 docker --version 명력을 입력하여 설치 확인한다.

% docker --version
Docker version 27.5.1, build 9f9e405

2. SonarQube Community Edition 설치하기

SonarQube 는 간단하게 터미널에서 아래 명령으로 SonarSource에서 공식적으로 제공하는 이미지를 다운로드하여 설치하고 실행할 수 있다.  SonarQube 는 디폴트로 사용하는 H2 데이터베이스 보다는  postgres 사용을 권장하고 있어 먼저 postgres 데이터베이스를 설치하고 같이 실행할 필요가 있다.

docker run -d --name sonarqube -p 9000:9000 sonarqube:lts-community

SonarQube는 여러 버전의 Docker 이미지를 제공하고 있다. 

태그(Tag)

설명

sonarqube:latest

최신 안정 버전

sonarqube:lts

최신 LTS (Long-Term Support) 버전

sonarqube:lts-community

무료 Community Edition LTS 버전

sonarqube:developer

Developer Edition (유료)

sonarqube:enterprise

Enterprise Edition (유료)

sonarqube:datacenter

Data Center Edition (유료)



postgres는 터미널에 아래와 같이 한 줄 명령어로 postgres 를 설치&실행 할 수 있다. 

docker run -d --name postgres \
  -e POSTGRES_USER=sonar \
  -e POSTGRES_PASSWORD=sonar \
  -e POSTGRES_DB=sonarqube \
  -p 5432:5432 \
  postgres:16

참고로 PostgreSQL 공식 Docker 이미지는 다양한 버전이 있는데 여기에서는 16 을 사용했다. 

태그 (Tag)

의미

postgres:latest

최신 안정 버전 (현재 기준 PostgreSQL 16)

postgres:16

PostgreSQL 16.x

postgres:15

PostgreSQL 15.x

postgres:14

PostgreSQL 14.x

postgres:13

PostgreSQL 13.x


이제 SonarQube 을 앞서 실행한 postres 와 함께 설치&실행 해보자.

docker run -d --name sonarqube \
  -p 9000:9000 \
  --link postgres \
  -e SONAR_JDBC_URL=jdbc:postgresql://postgres:5432/sonarqube \
  -e SONAR_JDBC_USERNAME=sonar \
  -e SONAR_JDBC_PASSWORD=sonar \
 sonarqube:lts-community

옵션

설명

docker run

새로운 컨테이너를 실행하는 명령

-d

컨테이너를 백그라운드(Detached Mode)에서 실행

--name sonarqube

컨테이너 이름을 sonarqube로 지정

-p 9000:9000

호스트의 9000번 포트를 컨테이너의 9000번 포트와 연결 (SonarQube 웹 UI)

--link postgre-container

SonarQube가 postgre-container 컨테이너와 통신할 수 있도록 설정 (Deprecated - 다른 방법 권장)

-e SONAR_JDBC_URL=jdbc:postgresql://postgres:5432/sonarqube

SonarQube가 PostgreSQL 데이터베이스 sonarqube에 연결하도록 설정

-e SONAR_JDBC_USERNAME=sonar

PostgreSQL 접속 시 사용할 DB 사용자명 설정

-e SONAR_JDBC_PASSWORD=sonar

PostgreSQL 접속 시 사용할 DB 비밀번호 설정

sonarqube:lts-community

실행할 Docker 이미지 (sonarqube의 LTS 버전, 무료 Community Edition)


참고로 여기에서는 postgres 와 sonarquber 가 서로 통신가능하게 --link 옵션을 사용했지만 안정성 이유로 --network 을 사용하는 것이 권장된다고 한다. 설치가 완료되면 브라우저에서 localhost:9000 포트로 접속한다. 디폴트 계정과 비밀번호는 admin 과 admin 이다.

Docker Desktop 도구를 사용하면 좀더 쉽게 도커 컨테이너 제어와 자원 사용량을 실시간으로 확인 할 수 있다.
Docker Desktop 화면

일단 위 과정을 한번하고나면 다음부터는 Docker Desktop 을 사용하여 쉽게 컨테이너를 조작할 수 있다.

2. SonarQube Community Edition 사용하기

한글이 익숙하다면 로그인 후 macketplace 메뉴에서 "Korean Pack Localization" 을 설치하면 간단하게 한글을 지원하게 된다.

코드 품질을 분석하는 기본적인 과정은 아래와 같다. 

❶ 프로젝트를 생성
❷ SonarScanner 설치 및 실행
❸ 분석결과 확인 

2.1 프로젝트를 생성

"프로젝트" 메뉴를 클릭하고 Community Edition 이 GitHub Private Repository 연동을 지원하지 않기 때문에 로컬에 프로젝트를 복제하여 분석 하기 위하여 "Manually" 을 선택한다.

존재하는 프로젝트가 없는 경우

프로젝트 이름을 입력하고 Setup 을 클릭하여 프로젝트를 생성한다.


2.2 토큰 생성

보안된 인증을 통해 자동화된 코드 분석을 실행할 수 있도록 토큰을 생성한다. Loaclly 을 클릭한다.


① 토큰 생성하기에서 생성하기를 클릭하여 토큰을 생성한다.




생성된 토큰을 별도로 저장하여 보관한다. Continue 클릭하면 다양한 환경에 바로 적용 가능한 스크립트를 보여준다. 



기존 프로젝트가 maven 을 지원하고 있어 maven 스크립트를 복사했다.

2.3 SonarScanner 설치 및 실행

SonarQube 서버와 연결하여 코드 품질을 분석하고 결과를 업로드하는 SonarScanner 은 아래와 같이 터미널에 입력하여 간단하게 설치할 수 있다.

brew install sonar-scanner

SonarScanner가 분석하는 요소는 아래와 같다.
  • Bug (버그): 코드에서 오류가 발생할 가능성이 있는 부분
  • Code Smell (코드 냄새): 유지보수성이 낮거나 개선이 필요한 코드
  • Vulnerability (보안 취약점): SQL Injection, XSS 같은 보안 문제
  • Coverage (테스트 커버리지): 단위 테스트가 얼마나 잘 작성되었는지
  • Duplications (코드 중복): 중복된 코드 블록 확인
설치 결과는 아래 명령으로 확인 할 수 있다.

sonar-scanner --version


이제 Git 에서 가져온 Maven 프로젝트에서 앞서 복사한 스크립트를 사용하여 실행한다.

mvn clean verify sonar:sonar \
-Dsonar.projectKey=my_project \
-Dsonar.host.url=http://localhost:9000 \
-Dsonar.login=your_generated_token

옵션

설명

mvn

Maven을 실행하는 명령어

clean

기존 빌드 파일을 삭제하고 새롭게 빌드

verify

테스트를 실행하고 빌드를 검증

sonar:sonar

SonarQube 분석을 실행하는 Maven 플러그인 (sonar-maven-plugin)

-Dsonar.projectKey=my_project

SonarQube에서 프로젝트를 구별하는 고유한 키

-Dsonar.host.url=http://localhost:9000

SonarQube 서버의 주소

-Dsonar.login=your_generated_token

SonarQube 인증을 위한 API 토큰



실행이 완료되면 SonarQube 웹에서 분석 결과 확인할 수 있다.



결과 화면

SonarQube 분석 결과을 보면 이 프로젝트는 다음과 같은 조치가 필요한 것으로 나타난다.
  1. Bugs, Vulnerabilities, Coverage, Duplications 항목에서 개선 필요
  2. 특히 Bugs (170개), Coverage (0%), 취약점 (13개)가 심각한 문제
  3. 보안 문제를 해결하고, 테스트 커버리지를 높이는 것이 가장 시급함
이제 SonarQube 에서 "Issues" 탭을 확인하고, 하나씩 문제를 해결해 나가면 된다. 

이슈 목록 화면

각 이슈를 클릭하면 해당 건에 대한 상세 화면으로 이동하게 된다.  이슈 내용을 확인하고 코드를 수정한다. 이슈 상세 페이지를 보면 이슈 상태를 변경할 수 있는 기능이 있는데  코드 수정 후 다시 로컬에서 SonarScanner 을 실행하기 때문에 문자가 해결되면 자동으로  Resolved(Fixed) 로 상태가 변경 된다.  


이슈 상세화면에서 "See all issues in this file" 클릭하여 해당 파일에 대한 목록만 보여지는데  이를 활용하면 파일 별로 작업을 진행 할 수도 있다. 

이슈 상세 화면

파일 단위로 필터 된 이슈 목록


코드를 수정하고 SonarScanner 을 동일하게 실행하면 결과가 반영되어 다시 분석결과가 업데이트 된다. 

3. 느낀점

자바 언어를 사용하는 프로젝트에 1주 정도 적용을 해보았는데 아래와 같은 점에서 아주 만족스러웠다.
  1. 좋은 코딩 습관을 위한 아주 좋은 도구이다. 코드에 대한  결함을 해결하면서 좋은 코드를 작성하는 방법을 자연스럽게 학습할 수 있었다.
    • Bug (버그): 코드에서 오류가 발생할 가능성이 있는 부분
    • Code Smell (코드 냄새): 유지보수성이 낮거나 개선이 필요한 코드
    • Vulnerability (보안 취약점): SQL Injection, XSS 같은 보안 문제
    • Coverage (테스트 커버리지): 단위 테스트가 얼마나 잘 작성되었는지
    • Duplications (코드 중복): 중복된 코드 블록 확인
  2. 자바 언어의 버전에 따른 좋은 코드를 지적해주기 때문에 코딩 스킬 향상에 도움이 되었다.
작성자: 시간:
라벨: , , , ,

댓글 없음:

댓글 쓰기

피드 구독하기: 댓글 (Atom)