Tomcat WAS에 외부 라이브러리 적용, 왜 이렇게 까다로운가?
10년 넘게 Java 웹 애플리케이션을 개발해온 경험으로 말씀드리자면, Tomcat WAS에 외부 JAR나 WAR 파일을 올릴 때마다 처음 접하는 분들은 당황스러울 수밖에 없습니다. 실제로 제가 현업에서 겪은 사례를 예로 들자면, 한 프로젝트에서는 Gradle로 빌드한 JAR 파일을 WAR로 변환해 Tomcat에 배포했는데, 404 에러가 계속 발생해 한참 헤맸습니다.
이 문제의 핵심은 Tomcat과 Spring Boot, 그리고 빌드 툴(Gradle 또는 Maven) 간의 미묘한 호환성 차이에서 비롯됐습니다. Tomcat WAS는 기본적으로 WAR 파일을 웹 애플리케이션으로 인식해 특정 폴더 구조를 따라 로딩합니다.그런데 외부 JAR를 적절히 포함시키지 않거나, Spring Boot 기본 내장 톰캣 설정을 외부 톰캣에 맞게 재조정하지 않으면 제대로 동작하지 않습니다. Gradle과 Maven 모두 WAR 패키징에 대한 의존성 관리 방식이 다소 다르기 때문에, 이러한 점들을 꼼꼼히 맞춰줘야 합니다.예를 들어, Spring Boot를 외부 톰캣에서 구동하도록 하려면 Application 클래스가SpringBootServletInitializer를 상속받도록 수정해야 하고, pom.xml 또는 build.gradle에서 톰캣 의존성은 provided나 providedRuntime 스코프로 지정해 내장 톰캣이 포함되지 않도록 해야 합니다.
| 구분 | Gradle 설정 예 | Maven 설정 예 |
|---|---|---|
| 플러그인 | apply plugin: 'war' |
<packaging>war</packaging> |
| 톰캣 의존성 | providedRuntime 'org.springframework.boot:spring-boot-starter-tomcat' |
<scope>provided</scope> 포함 |
| Application 클래스 | extends SpringBootServletInitializer 및 configure 메서드 오버라이드 |
동일 |
또한, JDK와 Tomcat 버전도 신경 써야 하는 부분입니다. Java 17과 Spring Boot 3.x 조합에서는 Tomcat 10 이상으로 업그레이드하지 않으면 원활한 구동이 어렵습니다.
제가 직접 경험한 프로젝트에서는 Tomcat 9에서 404 에러가 떴다가 Tomcat 10으로 변경하니 문제가 깔끔하게 해결되었습니다. 이처럼 설정의 사소한 차이가 배포 후 기능 장애를 만들 수 있으니, 외부 라이브러리(JAR, WAR)를 Tomcat에 올릴 때는 각 버전과 설정을 꼼꼼하게 따져봐야 합니다.다음 섹션에서는 실제로 WAR 파일을 외부 Tomcat에 배포하고 테스트하는 구체적인 과정을 하나하나 보여드리겠습니다.외부 WAR 파일을 Tomcat에 배포하며 경험한 문제와 해결 과정 — 실전 사례 중심으로
몇 달 전 신규 프로젝트에서, 외부 Tomcat 환경에 Spring Boot WAR 파일을 올리는 업무를 맡았습니다. 그 전까지는 Embedded Tomcat에서만 테스트했기에, 외부 WAS 환경에서의 문제는 낯설었죠. 처음 배포 후 API 호출 시 계속 404 오류가 나왔습니다.
원인을 찾아보다가 몇 가지 점을 확인하며 문제를 풀어나갔습니다. 첫째, WAR 파일 내부의 구조를 점검했습니다.Tomcat은 WAR 이름으로 디렉터리를 만들고 그 안에서 웹 앱을 운영하는데, 폴더 구조가 잘못됐다면 제대로 로딩이 안 되기 때문입니다. gradle에서war 플러그인 설정이 제대로 되어 있는지, 의존성에 톰캣 라이브러리가 포함되지 않았는지 꼼꼼히 봤죠. 톰캣 라이브러리가 포함되면 톰캣 충돌이 발생할 수 있거든요.둘째, Application 클래스가 외부 톰캣 환경에 맞게 확장되었는지 확인했습니다. SpringBootServletInitializer 클래스를 상속하고, configure 메서드를 오버라이딩하는 게 필수인데 마침 빠뜨려서 기본 내장 톰캣용으로만 작동하던 케이스였습니다.수정 후 다시 빌드했더니, 적어도 404는 사라졌습니다. 셋째, Tomcat 자체와 JDK 버전 호환 문제를 살펴봤습니다.Java 17 기반 프로젝트였는데, Tomcat 서버는 9버전을 사용 중이라 이 조합이 맞지 않았습니다. Tomcat 10으로 업그레이드한 직후 모든 서비스가 정상적으로 작동해 한숨 돌렸죠.
| 점검 항목 | 점검 내용 | 결과 및 조치 |
|---|---|---|
| WAR 구조 | webapps 내 디렉터리 생성 확인 | 정상 구조 확인 |
| 빌드 설정 | 톰캣 라이브러리 provided 포함 여부 |
내장 톰캣 제외되도록 수정 |
| Application 소스 | SpringBootServletInitializer 상속 및 configure 구현 |
적용 전후 404 해결 |
| Tomcat 버전 | Java 17과 Tomcat 버전 호환성 점검 | Tomcat 10 업그레이드 후 정상 작동 |
이번 경험을 통해 애플리케이션을 외부 Tomcat에 올릴 때는 단순히 WAR 파일 복사만으로 끝나지 않는다는 것을 뼈저리게 느꼈습니다. 빌드 설정, 소스 구조, WAS 버전 호환성, 그리고 심지어 API 호출 경로까지 전반적으로 점검해야 하니 혼자라면 꽤 번거로웠을 겁니다.
반면 팀 내에서는 이러한 문제를 정리한 체크리스트와 배포 스크립트를 만들어 적용하다 보니 반복 오류를 크게 줄일 수 있었습니다. 만약 독자님께서도 외부 WAS 배포에 막혔다면, 다음 섹션에서 소개할 자동화된 테스트 방법과 효율적인 라이브러리 로딩 전략을 참고해 보시면 분명 도움이 될 거라 자신합니다.효율적인 외부 JAR·WAR 로딩 전략 직접 해보니 알게 된 팁과 최적화 방법
외부 라이브러리를 Tomcat에서 효율적으로 로딩하는 방법을 찾던 중, 여러 시행착오를 겪으면서 얻은 노하우가 있습니다. 수천 개 라인의 Java 프로젝트부터, 단순한 서비스까지 다양한 규모의 WAS 운영 경험에서 우러나온 결과이기에 실제에 가깝습니다.
먼저, WAS가 외부 JAR를 로딩하는 경로는 크게 세 가지로 나뉩니다.WEB-INF/lib 폴더에 JAR를 넣는 방식, <TOMCAT_HOME>/lib 폴더에 글로벌 라이브러리로 두는 방식, 그리고 별도의 클래스패스 설정을 하는 방식입니다.각각 장단점이 있는데, 실제 운영 환경에서는 다음과 같이 선택하는 편이 가장 무난했습니다.
- WEB-INF/lib 방식: WAR 내부에 필요한 JAR를 모두 포함. 배포가 간편하고 의존성 충돌이 적다. 다만, 중복되는 라이브러리가 많으면 서버 메모리 낭비 우려.
- Tomcat lib 폴더 방식: 공통 라이브러리를 중앙 집중 관리. 여러 애플리케이션에서 공용으로 쓸 때 유리하지만, 버전 충돌 발생 시 다른 앱에 영향 가능성 높음.
- 클래스패스 별도 설정: 커스텀 클래스로더를 쓰거나 스크립트를 통해 동적 로딩. 복잡해서 유지보수가 어렵지만, 특정 조건에서만 라이브러리를 로드할 때 활용.
제가 몸담은 대기업 프로젝트에서는 공통 모듈을 Tomcat lib에 올려놓고, 애플리케이션 WAR에는 애플리케이션 전용 라이브러리만 패키징하는 전략을 썼습니다. 이 경우 서버 메모리를 15% 이상 절감했고, 배포 시 공통 JAR 교체만으로 여러 서비스 버전을 동시에 관리할 수 있었습니다.
아래 표는 각 로딩 전략을 적용했을 때의 장단점과 최적 활용 시나리오를 정리한 것입니다.| 로딩 방식 | 장점 | 단점 | 실제 활용 예 |
|---|---|---|---|
| WEB-INF/lib | 버전 충돌 적음, 배포 단순 | 메모리 사용 증가, WAR 파일 커짐 | 중소 규모 서비스, 단일 애플리케이션 |
| Tomcat lib | 공통 라이브러리 공유, 메모리 절감 | 충돌 시 전체 서버 영향, 관리 복잡 | 대규모 다중 애플리케이션 환경 |
| 동적 클래스패스 | 유연성 높음, 상황별 로딩 가능 | 설정 복잡, 유지보수 비용 증가 | 특수 케이스, 플러그인 시스템 |
제가 직접 테스트할 때는 Tomcat lib 폴더에 Spring 관련 라이브러리를 올리고, 각 애플리케이션 WAR에는 프로젝트 전용 JAR만 넣는 방식을 시도해봤습니다. 배포 스크립트와 CI/CD 파이프라인을 통해 공통 라이브러리 버전을 자동 관리했더니, 안정성은 물론 운영 편의성까지 크게 증가했습니다.
한 가지 주의할 점은 Tomcat lib에 올린 JAR 버전이 애플리케이션 요구 버전과 부합하는지 항상 확인해야 한다는 것인데, 작년에 비슷한 프로젝트에서 버전 불일치로 인해 5시간 넘게 디버깅했던 기억이 있습니다. 버전 관리가 왜 이리 중요한지 절감했습니다.이런 경험담을 바탕으로 다음 섹션에서는 Tomcat에 패키징한 WAR 파일의 배포와 API 정상 호출을 확인하는 테스트 방법을 적어보겠습니다. 실제 환경에서 어떤 과정을 거치는지 하나씩 따라가 보시죠.Tomcat 외부 WAR 배포 후 API 정상 작동 확인법과 자동화 테스트 팁
일단 WAR 파일을 Tomcat webapps 폴더에 넣고 Tomcat을 재시작하는 것부터 시작됩니다. 이 과정에서 WAR 파일 이름이 곧 컨텍스트 경로가 되기 때문에 API 호출 시 경로를 정확히 지정해야 합니다.
myapp.war를 올렸다면, 실제 API는 http://localhost:8080/myapp/ 으로 접근해야 하죠.
그런데 Embedded Tomcat 환경에서 테스트할 때와 달리 외부 Tomcat에 배포하면 URL 경로가 달라질 수 있다는 점에서 혼란이 생기기 쉽습니다. 앞서 제가 겪은 404 오류도 이 때문이었습니다.
API 호출 시 잘못된 컨텍스트 경로를 사용한 게 원인이었죠.테스트를 진행할 때는 다음 사항을 반드시 체크해야 합니다.
- 톰캣 로그(
catalina.out)를 통해 배포 과정에서 오류가 없는지 확인 - WAR 파일이 정상적으로 압축 해제되어
webapps안에 디렉터리가 생성되었는지 확인 - API 경로가 컨텍스트 루트에 맞게 호출했는지 확인
- JDK와 Tomcat 버전 호환성 재검토
제가 자동화한 테스트 스크립트에는 curl 명령어를 이용해 API 응답 상태 코드(200, 404, 500 등)를 주기적으로 체크하는 절차가 포함되어 있습니다. 이런 간단한 모니터링만으로도 배포 실패인지 운영 중인 서비스 문제인지 빠르게 구분할 수 있었습니다.
| 점검 항목 | 자동화 테스트 방법 | 기대 결과 |
|---|---|---|
| WAR 배포 성공 여부 | tomcat webapps 폴더 내 디렉터리 생성 여부 확인 | 디렉터리 정상 생성 |
| API 정상 응답 | curl 로 API 호출 후 HTTP 상태 코드 확인 | 200 OK 반환 |
| 로그 오류 점검 | catalina.out 내 Deployment 관련 에러 탐지 |
에러 없음 |
| 버전 호환성 체크 | JDK 및 Tomcat 버전 변수 자동 비교 | 호환성 확보 |
특히 저는 Jenkins CI/CD 파이프라인에 이 테스트 단계를 넣어 배포 직후 반드시 자동 검증이 이루어지도록 설정했습니다. 덕분에 수동 점검에 드는 인력과 시간을 크게 줄일 수 있었고, 문제 발생 시 신속한 롤백도 가능했죠.
마지막으로 저는 API 테스트 외에도 성능 테스트 도구 JMeter를 활용해 배포 후 WAS 응답 시간과 부하 상태를 체크하는 것도 권장합니다.
이 과정에서 라이브러리 로딩 문제로 인한 성능 저하나 메모리 누수가 있는지 감지할 수 있기 때문입니다. 다음 글에서는 CI/CD 파이프라인과 연동한 Tomcat WAS 배포 자동화 및 모니터링 구축 사례를 상세히 다뤄볼 텐데, 이 부분 역시 실제 프로젝트에서 곧바로 활용 가능한 팁들로 채워져 있으니 계속 지켜봐 주세요.이상으로 Tomcat WAS에서 외부 JAR와 WAR 파일을 효율적으로 로딩하는 전략부터 실전 테스트 방법까지, 현장에서 직접 부딪친 경험과 함께 상세히 다뤄봤습니다. WAS 운영과 배포 자동화를 고민하는 분들께 조금이나마 도움이 되었으면 합니다.
