[완벽 정리] Docker + Tomcat + Spring Boot 호환성 문제 해결 가이드

안녕하세요 , 오늘은 Spring Boot 프로젝트를 Docker Tomcat에 배포하려는 과정에서 발생한 문제 중,Tomcat 9에서는 동작하지 않고 Tomcat 10에서는 정상 동작하는 이유에 대해 정리하고,그에 따른 원인 분석과 해결 방법을 함께 소개드립니다.

  👉 spring 고도화 프로잭트를 더 알고 싶다면 ( 클릭 )

[# Spring boot] 3년 차 개발자의 리팩토링 실전기: Spring 레거시 → Spring Boot 완벽 마이그레이션 가이

 

 

 

 

 핵심 내용 정리

• Docker 환경에서 Tomcat과 Spring Boot를 활용할 때 자주 겪는 호환성 문제 정리
• Tomcat 9.x vs Tomcat 10.x (javax vs jakarta 패키지 차이)
• Docker Compose 네트워크 설정 및 컨테이너 간 DNS 설정 문제
• Spring Boot 애플리케이션의 WAR 배포 설정 및 주의사항

 

 자주 발생하는 에러 현상

1️⃣ Tomcat 버전 및 패키지 호환성 문제 (javax vs jakarta)

에러 현상:

java.lang.NoClassDefFoundError: javax/servlet/ServletContext
또는
java.lang.NoSuchMethodError: jakarta.servlet.ServletContext...

원인 분석:

• Tomcat 9.x → javax.servlet 패키지 사용
• Tomcat 10.x → jakarta.servlet 패키지 사용
• Spring Boot 3.x 이상은 jakarta EE 기반이므로 Tomcat 10.x를 사용해야 함

해결 방법:

• Spring Boot 3.x 이상 → Tomcat 10.x 사용 (jakarta 기반)
• Spring Boot 2.x 이하 → Tomcat 9.x 사용 (javax 기반)

 

2️⃣ Docker 컨테이너 간 네트워크 연결 실패

에러 현상:

nginx: [emerg] host not found in upstream "tomcat"...
또는
HTTP 상태 404 – 찾을 수 없음

원인 분석:

• Docker Compose에서 같은 네트워크를 명시하지 않아 DNS로 다른 컨테이너를 찾지 못함
• Nginx의 proxy_pass 설정에서 잘못된 호스트명 사용

해결 방법:

docker-compose.yml 예시:

version: '3.8'

services:
  nginx:
    image: nginx:latest
    ports:
      - "80:80"
    networks:
      - app-network

  tomcat:
    image: tomcat:10.1
    expose:
      - "8080"
    networks:
      - app-network

networks:
  app-network:

Nginx default.conf 예시:

server {
    listen 80;
    server_name tomcat.localhost;

    location / {
        proxy_pass http://tomcat:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

호스트 OS의 /etc/hosts에 추가:

127.0.0.1 tomcat.localhost

 

 

3️⃣ WAR 파일 경로 설정 문제

에러 현상:

HTTP 상태 404 – 찾을 수 없음

원인 분석:

• Tomcat이 기본 루트 경로(/)를 찾을 때 WAR 파일 이름이 ROOT.war가 아니면 접근 불가능

해결 방법:

• WAR 파일 이름을 ROOT.war로 변경하여 Tomcat webapps에 배포
• 다른 이름의 WAR 파일일 경우 경로를 명시적으로 지정하여 접근 (예: myapp.war → /myapp)

 

4️⃣ DB 접속 권한 문제 (Spring Boot)

에러 현상:

java.sql.SQLInvalidAuthorizationSpecException: Access denied for user 'root'@'...' (using password: YES)

원인 분석:

• Docker 컨테이너의 DB 접근 시 IP 주소 허용 문제
• Spring Boot 설정 파일의 DB 계정 정보 오류

해결 방법:

Docker 컨테이너 내부에서 DB 권한 부여:

GRANT ALL PRIVILEGES ON *.* TO 'root'@'%' IDENTIFIED BY 'password';
FLUSH PRIVILEGES;

Spring Boot의 application.yml 설정 확인:

spring:
  datasource:
    url: jdbc:mariadb://host.docker.internal:3306/mydb
    username: root
    password: password
  jpa:
    properties:
      hibernate.dialect: org.hibernate.dialect.MariaDBDialect

 

 

 

최종 요약

• Spring Boot 버전과 Tomcat 버전을 반드시 맞춰 사용
• Docker Compose 사용 시 명확한 네트워크 정의
• WAR 파일의 이름과 Tomcat의 배포 경로 정확히 확인
• DB 접근 권한과 Spring 설정 파일의 일관성 유지