Tomcat 힙 설정은 CATALINA_OPTS에 넣어야 하는 이유

Tomcat JVM 튜닝하다 보면 -Xmx나 GC 옵션을 JAVA_OPTS에 넣을지 CATALINA_OPTS에 넣을지 헷갈립니다. 공식 catalina.sh 주석에 정리돼 있습니다. CATALINA_OPTS는 "start, run, debug" 명령에서만 적용되고, JAVA_OPTS는 "any command", 즉 stop을 포함한 모든 명령에서 적용됩니다. 그래서 문서도 힙 크기, GC 로깅, JMX 포트 같은 건 CATALINA_OPTS에 넣으라고 권합니다.

왜 중요하냐면, -Xmx4g를 JAVA_OPTS에 넣으면 catalina.sh stop으로 서버를 내릴 때 종료용으로 잠깐 뜨는 JVM까지 4G를 잡으려 듭니다. 메모리가 빠듯한 장비에서는 이 정지 JVM이 뜨다가 실패해 종료가 꼬일 수 있습니다. 반대로 stop 프로세스나 version 조회에도 공통으로 걸어야 하는 값(예: 특정 시스템 프로퍼티)만 JAVA_OPTS에 두면 됩니다.

# 힙, GC, JMX 등 Tomcat 본체에만 필요한 건 여기
export CATALINA_OPTS="-Xms1g -Xmx1g -XX:+UseG1GC"

# stop 포함 모든 명령에 공통으로 줄 값만 여기
export JAVA_OPTS="-Dfile.encoding=UTF-8"

주석 마지막 문장이 핵심입니다. "most options should go into CATALINA_OPTS." 헷갈리면 대부분 CATALINA_OPTS로 보내면 됩니다.

🔗 https://raw.githubusercontent.com/apache/tomcat/main/bin/catalina.sh