초보자도 쉽게 따라하는 Linux Tomcat WAR 배포 튜토리얼

초보자도 쉽게 따라하는 Linux Tomcat WAR 배포 튜토리얼

리눅스 서버에 Apache Tomcat을 설치하고 WAR 파일을 배포하는 전체 과정을 단계별로 설명합니다. 이 튜토리얼은 Ubuntu 22.04와 CentOS 8 환경에서 Java 17과 Tomcat 10.1을 기준으로 작성되었으며, 실제 동작하는 코드 예제와 트러블슈팅 팁을 포함합니다. 초보 개발자도 쉽게 따라할 수 있도록 구성되었습니다.

1. 튜토리얼 개요

Apache Tomcat은 자바 기반의 웹 애플리케이션을 호스팅하기 위한 오픈소스 서블릿 컨테이너입니다. 이 가이드에서는 Tomcat 10.1 버전을 사용하여 WAR 파일을 배포하는 방법을 다룹니다. 지원 OS는 Ubuntu 22.04와 CentOS 8이며, 두 배포판 모두에서 테스트를 완료했습니다. 전체 프로세스는 다음과 같은 단계로 구성됩니다:

  1. 사전 준비: Java 설치 확인, 방화벽 설정, WAR 파일 준비
  2. Tomcat 설치: 패키지 관리자 사용 vs 바이너리 설치 방법 비교
  3. 서비스 관리: systemd를 이용한 서비스 등록 및 자동 실행 설정
  4. WAR 배포: webapps 디렉토리에 WAR 파일 복사 및 자동 배포 확인
  5. 문제 해결: 404 에러, Java 버전 문제, 보안 정책 조정
  6. 고급 설정: 모니터링 및 추가 학습 자료 제공

참고: 공식 문서에서는 Tomcat 10.1 다운로드 페이지에서 최신 버전을 확인할 수 있습니다. 또한 Oracle Java 17 설치 가이드를 참고하면 Java 설치에 도움이 됩니다.

2. 사전 준비 사항

2.1 Java 17+ 설치 확인

Tomcat 10.1은 Java 17 이상을 필수로 요구합니다. 다음 명령어로 Java 설치 상태를 확인하세요:

java -version

출력 결과가 17.x.x로 시작하지 않으면 Java 17을 설치해야 합니다. Ubuntu에서는 다음 명령어로 설치할 수 있습니다:

sudo apt update
sudo apt install openjdk-17-jdk -y

CentOS에서는:

sudo yum install java-17-openjdk-devel -y

설치 후 JAVA_HOME 환경 변수를 설정해야 합니다. Ubuntu/CentOS 공통 설정 방법:

echo 'export JAVA_HOME=$(readlink -f /usr/bin/java | sed "s:/bin/java::")' >> ~/.bashrc
echo 'export PATH=$JAVA_HOME/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

2.2 방화벽 설정

Tomcat 기본 포트는 8080입니다. SSH(22)와 Tomcat(8080) 포트를 열어주세요:

  • Ubuntu:

    sudo ufw allow 22/tcp
sudo ufw allow 8080/tcp

  • CentOS:

    sudo firewall-cmd --permanent --add-port=22/tcp
sudo firewall-cmd --permanent --add-port=8080/tcp
sudo firewall-cmd --reload

2.3 WAR 파일 준비

샘플 WAR 파일이 없다면 Spring Boot 프로젝트를 생성해 테스트용 WAR를 만들 수 있습니다. 다음 pom.xml을 사용하세요:

<project xmlns="http://maven.apache.org/POM/4.0.0">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>demo</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  <packaging>war</packaging>
  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.1.5</version>
    <relativePath/> <!-- lookup parent from repository -->
  </parent>
  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-web</artifactId>
      <exclusions>
        <exclusion>
          <groupId>org.springframework.boot</groupId>
          <artifactId>spring-boot-starter-tomcat</artifactId>
        </exclusion>
      </exclusions>
    </dependency>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-tomcat</artifactId>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>jakarta.servlet</groupId>
      <artifactId>jakarta.servlet-api</artifactId>
      <version>6.0.0</version>
      <scope>provided</scope>
    </dependency>
  </dependencies>
  <build>
    <plugins>
      <plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
      </plugin>
    </plugins>
  </build>
</project>

그리고 간단한 컨트롤러 클래스를 작성하세요:

package com.example.demo;

import org.springframework.boot.web.servlet.support.SpringBootServletInitializer;
import org.springframework.boot.builder.SpringApplicationBuilder;
import org.springframework.stereotype.Component;
import org.springframework.web.bind.annotation.*;

@RestController
public class HelloController extends SpringBootServletInitializer {
    @Override
    protected SpringApplicationBuilder configure(SpringApplicationBuilder application) {
        return application.sources(HelloController.class);
    }
    
    @GetMapping("/")
    public String home() {
        return "Hello from Tomcat!";
    }
}

Maven으로 WAR를 빌드하려면:

mvn clean package

생성된 WAR 파일은 target/demo-0.0.1-SNAPSHOT.war에 위치합니다.

3. 단계별 설치 및 배포

3.1 Tomcat 설치 방법 비교

Tomcat 설치에는 두 가지 주요 방법이 있습니다:

  1. 패키지 관리자 사용 (apt/yum)

    • 장점: 시스템 통합이 용이
    • 단점: 최신 버전 지원이 느림
    • Ubuntu: 
      sudo apt install tomcat10 -y
    • CentOS: 
      sudo yum install tomcat -y

  2. 바이너리 설치 (권장)

    • 장점: 최신 버전 설치 가능
    • 단점: 수동 설정 필요
    • 공식 사이트에서 압축 해제: 
      cd /opt
sudo wget https://downloads.apache.org/tomcat/tomcat-10/v10.1.12/bin/apache-tomcat-10.1.12.tar.gz
sudo tar -xzvf apache-tomcat-10.1.12.tar.gz
sudo ln -s apache-tomcat-10.1.12 tomcat

팁: 프로덕션 환경에서는 바이너리 설치가 권장됩니다. 패키지 관리자는 때로는 오래된 버전을 포함할 수 있기 때문입니다.

3.2 systemd 서비스 등록

Tomcat을 백그라운드 서비스로 실행하려면 systemd를 설정해야 합니다. /etc/systemd/system/tomcat.service 파일을 생성하세요:

[Unit]
Description=Apache Tomcat 10 Web Application Container
After=network.target

[Service]
Type=forking

Environment=CATALINA_PID=/opt/tomcat/temp/tomcat.pid
Environment=CATALINA_HOME=/opt/tomcat
Environment=CATALINA_BASE=/opt/tomcat
Environment='JAVA_HOME=/usr/lib/jvm/java-17-openjdk'
Environment='JAVA_OPTS=-Djava.security.egd=file:/dev/./urandom -Djava.awt.headless=true'

ExecStart=/opt/tomcat/bin/startup.sh
ExecStop=/opt/tomcat/bin/shutdown.sh
ExecReload=/opt/tomcat/bin/shutdown.sh ; /opt/tomcat/bin/startup.sh

User=tomcat
Group=tomcat
UMask=0007
RestartSec=10
Restart=always

[Install]
WantedBy=multi-user.target

서비스 활성화 및 시작:

sudo systemctl daemon-reload
sudo systemctl enable tomcat
sudo systemctl start tomcat

3.3 WAR 파일 배포

WAR 파일은 Tomcat의 webapps 디렉토리에 복사하면 자동으로 배포됩니다:

cp demo-0.0.1-SNAPSHOT.war /opt/tomcat/webapps/

배포 상태를 확인하려면 로그 파일을 확인하세요:

cat /opt/tomcat/logs/catalina.out

브라우저에서 http://[서버IP]:8080/demo로 접속하여 “Hello from Tomcat!” 메시지가 표시되는지 확인하세요.

4. 트러블슈팅

4.1 404 에러 해결

WAR 파일이 배포되었지만 404 에러가 발생한다면 다음을 확인하세요:

  1. 로그 확인:

    tail -f /opt/tomcat/logs/catalina.out

    에러 메시지가 있는지 확인합니다.

  2. 컨텍스트 패스 확인: WAR 파일 이름이 demo.war라면 접근 주소는 http://[서버IP]:8080/demo입니다.

  3. 서버 재시작:

    sudo systemctl restart tomcat

4.2 Java 버전 불일치 문제

Tomcat 10.1은 Java 8 이상을 지원하지만, 최신 기능을 사용하려면 Java 17이 필요합니다. 다음 명령어로 사용 중인 Java 버전을 확인하세요:

/opt/tomcat/bin/version.sh

만약 잘못된 Java 버전이 사용된다면 CATALINA_OPTS에 Java 경로를 명시적으로 지정하세요:

export CATALINA_OPTS="$CATALINA_OPTS -Djava.home=/usr/lib/jvm/java-17-openjdk"

4.3 SELinux/AppArmor 보안 정책

SELinux나 AppArmor가 활성화된 환경에서는 Tomcat이 파일에 접근하지 못할 수 있습니다. Ubuntu에서는 AppArmor를 일시적으로 비활성화해 테스트할 수 있습니다:

sudo systemctl stop apparmor

CentOS에서 SELinux 모드 확인:

getenforce

SELinux를 일시적으로 Permissive 모드로 전환:

sudo setenforce 0

영구적으로 비활성화하려면 /etc/selinux/config 파일을 편집하세요:

SELINUX=disabled

5. 마치며

이 튜토리얼에서는 Linux 서버에 Tomcat을 설치하고 WAR 파일을 배포하는 전체 과정을 다뤘습니다. 핵심 내용을 요약하면 다음과 같습니다:

  1. Tomcat 10.1 설치에는 바이너리 방식이 최신 버전 사용에 유리합니다.
  2. WAR 파일은 webapps 디렉토리에 복사만으로 자동 배포됩니다.
  3. 트러블슈팅 시 로그 파일과 보안 정책을 반드시 확인해야 합니다.

추가로 학습할 자료:

모니터링 시스템 구축을 원한다면 JMXTrans와 Grafana를 연동하는 방법을 고려해보세요. 이는 서버 리소스 사용량과 애플리케이션 성능을 실시간으로 모니터링할 수 있게 해줍니다.