SonarQube 실행 오류: vm.max_map_count 값이 뭐길래 서버가 안 뜰까?

SonarQube를 Docker로 띄웠는데 다음과 같은 증상을 겪은 적이 있을 것이다.

• 컨테이너는 Up 상태
• 포트(9000)도 열려 있음
• 그런데 curl http://localhost:9000 하면 Connection refused
• 로그를 보면 Elasticsearch가 계속 죽었다 살아남

로그에는 보통 아래와 같은 메시지가 반복된다.

 

bootstrap check failure: max virtual memory areas vm.max_map_count [65530] is too low, increase to at least [262144]

이 글에서는 이 오류의 정확한 원인과
vm.max_map_count가 도대체 무엇인지,
왜 SonarQube에서 필수인지 정리한다.

---

vm.max_map_count란 무엇인가?

vm.max_map_count는 리눅스 커널 파라미터다.

하나의 프로세스가 생성할 수 있는
메모리 매핑 영역(memory map)의 최대 개수

를 의미한다.

리눅스에서 파일이나 메모리를 프로세스 주소 공간에 매핑할 때
mmap() 시스템 콜이 사용되는데,
이때 생성되는 가상 메모리 영역(VMA, Virtual Memory Area) 의 개수 제한이 바로 vm.max_map_count다.

---

왜 Elasticsearch에서 문제가 되는가?

SonarQube 내부에는 Elasticsearch가 포함되어 있다.
(9.x LTS 기준 ES 7.x 사용)

Elasticsearch는 다음과 같은 특성을 가진다.

• 대량의 인덱스 파일을 사용
• Lucene 기반
• 파일을 메모리 매핑(mmap) 방식으로 접근
• 작은 mmap 영역을 매우 많이 생성

즉,

Elasticsearch = mmap을 엄청 많이 쓰는 프로그램

이다.

---

기본값이 왜 문제인가?

CentOS 7 / RHEL 계열의 기본값은 다음과 같다.

 

vm.max_map_count = 65530

이 값은 일반적인 서버 프로세스에는 충분하지만,
Elasticsearch에는 절대적으로 부족하다.

그래서 Elasticsearch는 부팅 시 bootstrap check를 수행하고,
값이 부족하면 의도적으로 프로세스를 종료한다.

이게 바로 SonarQube가 다음 상태가 되는 이유다.

• 컨테이너는 실행 중
• 포트는 열림
• 하지만 내부 Elasticsearch가 즉시 종료
• SonarQube 전체 서비스 중단

---

왜 Docker인데 호스트 설정을 바꿔야 할까?

중요한 포인트 하나.

Docker 컨테이너는 커널을 공유한다.

즉,

• 컨테이너 내부에서 Elasticsearch가 실행되더라도
• 실제 커널 파라미터는 호스트 OS 값을 그대로 사용한다.

그래서 컨테이너 안에서 아무리 설정해도 소용없고,
호스트 서버에서 vm.max_map_count를 올려야 한다.

---

SonarQube / Elasticsearch가 요구하는 값

공식 문서 기준 최소 요구값:

 

vm.max_map_count >= 262144

---

해결 방법 (정석)

1. 현재 값 확인

 

sysctl vm.max_map_count

---

2. 즉시 적용 (재부팅 전까지 유효)

 

sysctl -w vm.max_map_count=262144

---

3. 재부팅 후에도 유지 (반드시 필요)

방법 1: sysctl.conf

 

echo "vm.max_map_count=262144" >> /etc/sysctl.conf

방법 2: 권장 방식 (설정 파일 분리)

 

cat <<EOF >/etc/sysctl.d/99-sonarqube.conf vm.max_map_count=262144 EOF sysctl --system

---

4. SonarQube 재시작

 

docker restart sonarqube

또는

 

docker-compose restart

---

정상 동작 확인

로그에서 아래 문구가 나와야 한다.

 

docker logs -f sonarqube

정상 상태:

 

Process[web] is up SonarQube is up

그리고 접속 확인:

 

curl http://localhost:9000

---

왜 이런 체크를 강제로 할까?

Elasticsearch는 운영 환경에서 mmap 부족으로 데이터 손상이나
예측 불가능한 장애가 발생하는 것을 막기 위해
bootstrap 단계에서 아예 실행을 거부한다.

즉, 이 에러는:

“설정이 잘못됐으니 차라리 지금 죽겠다”

라는 의도된 안전장치다.

---

정리

• vm.max_map_count는 프로세스가 만들 수 있는 메모리 매핑 영역 개수 제한
• Elasticsearch는 mmap을 대량으로 사용
• 기본값(65530)으로는 SonarQube 실행 불가
• 262144 이상으로 반드시 설정 필요
• Docker를 써도 호스트 커널 설정은 필수

---

한 줄 요약

SonarQube가 안 뜬다면,
방화벽보다 먼저 vm.max_map_count를 의심하자