리눅스 서버에 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. 트러블슈팅 시 로그 파일과 보안 정책을 반드시 확인해야 합니다.

추가로 학습할 자료:

• Tomcat 공식 문서
• Spring Boot WAR 배포 가이드

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

SpringBoot 애플리케이션에 GitHub Actions를 활용한 CI/CD 파이프라인을 구축하고, 실제 운영 환경에서 발생하는 문제를 해결하는 방법을 단계별로 설명합니다. 이 가이드는 JDK 설치부터 클라우드 배포까지 전체 워크플로우를 다루며, 실패 사례별 트러블슈팅 기법을 포함합니다.

튜토리얼: SpringBoot CI/CD 기본 구성

1. GitHub 리포지토리 연결 및 기본 Workflow 생성

1. SpringBoot 프로젝트를 GitHub에 업로드합니다.

   git init
   git add .
   git commit -m "Initial commit"
   git branch -M main
   git remote add origin https://github.com/<your-id>/<repo-name>.git
   git push -u origin main
   

2. .github/workflows/springboot-ci-cd.yml 파일을 생성합니다.

2. 기본 Workflow YAML 구성

name: SpringBoot CI/CD

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - name: Set up JDK 17
      uses: actions/setup-java@v4
      with:
        java-version: '17'
        distribution: 'temurin'
    - name: Build with Gradle
      run: ./gradlew build
    - name: Build Docker image
      run: |
        docker build -t my-springboot-app:latest .
        docker tag my-springboot-app:latest \
          $AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/my-springboot-app:latest
    - name: Push to ECR
      run: |
        aws ecr get-login-password --region $AWS_REGION | \
          docker login --username AWS --password-stdin $AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com
        docker push $AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/my-springboot-app:latest
      env:
        AWS_ACCOUNT_ID: ${{ secrets.AWS_ACCOUNT_ID }}
        AWS_REGION: ${{ secrets.AWS_REGION }}

팁: Maven 사용 시 ./mvnw clean package로 변경합니다. Dockerfile이 프로젝트 루트에 위치해야 합니다.

3. GitHub Secrets 설정

• AWS 계정의 AWS_ACCOUNT_ID와 AWS_REGION을 Secrets에 등록
• Azure App Service 사용 시 AZURE_WEBAPP_NAME과 AZURE_CREDENTIALS 추가

트러블슈팅: CI/CD 실패 주요 사례

1. 빌드 실패 사례

• Java 버전 불일치:

  Error: Java version "1.8.0_292" is not supported by Gradle
  

  → setup-java 액션의 java-version을 프로젝트 요구사항에 맞춰 수정
• Gradle wrapper 미포함:

  /bin/sh: ./gradlew: No such file or directory
  

  → gradlew 바이너리 포함 여부 확인 (Gradle wrapper 사용 필수)
• 의존성 다운로드 실패:

  Could not transfer artifact com.example:library:jar:1.0.0
  

  → 방화벽 설정 확인 또는 --no-daemon 플래그 추가

2. 배포 실패 사례

• IAM 권한 문제:

  User is not authorized to perform ecr:PutImage
  

  → AWS ECR 접근 권한이 있는 IAM 역할 생성 후 Secrets에 자격 증명 등록
• Docker 태그 충돌:

  manifest for my-springboot-app:latest not found
  

  → docker pull로 기존 이미지 삭제 후 재시도
• Helm chart 오류:

  failed: Invalid value: : invalid type for io.fabric8.kubernetes.client.dsl.base.CustomResourceDefinitionContext
  

  → Helm 차트 버전 호환성 확인 및 helm dependency update 실행

3. 캐시 미적용 문제

GET https://jcenter.bintray.com/...

→ Gradle/Maven 의존성 캐시 추가:

- name: Cache Gradle packages
  uses: actions/cache@v3
  with:
    path: ~/.gradle/caches
    key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*') }}
    restore-keys: |
      ${{ runner.os }}-gradle-

문제 해결: 단계별 검증 방법

1. 로컬에서 Workflow 테스트

act CLI로 로컬에서 워크플로우를 시뮬레이션합니다.

brew install nektos/act/act
act --pull-request --pull-request-head-sha=$(git rev-parse HEAD)

2. 디버그 로그 활성화

워크플로우 단계에 set -x 추가:

- name: Debug Docker build
  run: |
    set -x
    docker build -t my-springboot-app:latest .

3. Self-hosted Runner 로그 분석

SSH로 러너 서버에 접속해 직접 로그 확인:

journalctl -u github-actions-runner.service -f

4. 품질 검증 도구 연동

• JUnit 테스트 결과: gradle test jacocoTestReport 추가
• SonarQube 분석:

- name: Run SonarQube Scanner
  uses: SonarSource/sonarqube-scan-action@master
  with:
    projectKey: my-springboot-project
    projectName: SpringBoot Demo

참고 문서

• GitHub Actions Java with Gradle 문서
• AWS ECR Docker 푸시 가이드

주의사항: 프로덕션 환경에서는 main 브랜치 외에 develop 브랜치에 대한 별도 워크플로우를 구성하는 것이 안전합니다. 이미지 태그 전략으로는 SHA 기반 태그를 권장합니다.

AWS CodePipeline은 서버리스 CI/CD 서비스로, 코드 변경부터 배포까지 자동화된 워크플로우를 제공합니다. 하지만 복잡한 인프라 환경에서 권한 오류, 아티팩트 누락, 빌드 스크립트 실패 등 다양한 문제가 발생할 수 있습니다. 이 가이드에서는 CodePipeline의 기본 구성부터 모니터링, 트러블슈팅, 예방 조치까지 단계별로 설명합니다. 실제 동작하는 코드 예제와 AWS 공식 문서를 참고해 문제를 체계적으로 해결하는 방법을 제시합니다.

1. 튜토리얼: CodePipeline 기본 구성 및 모니터링

1.1 CodePipeline 구조 이해

CodePipeline은 Source → Build → Deploy 3단계로 구성됩니다. 각 단계는 독립적인 액션으로 관리되며, 실패 시 롤백이 가능합니다. 예를 들어, GitHub에서 코드를 가져온 후 CodeBuild로 빌드하고, CodeDeploy로 EC2에 배포하는 파이프라인을 구성할 수 있습니다.

팁: 파이프라인 설계 시 각 단계의 출력 아티팩트가 다음 단계로 전달되는지 확인해야 합니다. S3 버킷 권한 문제로 아티팩트가 누락되면 파이프라인이 중단됩니다.

1.2 CloudWatch 로그 연동 방법

CodePipeline 자체의 로그는 제한적이므로, 각 단계에서 CloudWatch Logs를 활성화해야 합니다. 예를 들어 CodeBuild 프로젝트의 로그 그룹을 생성하려면 다음 AWS CLI 명령어를 사용합니다:

# CodeBuild 로그 그룹 생성
aws logs create-log-group \
  --log-group-name /aws/codebuild/your-project-name \
  --retention-in-days 14

1.3 파이프라인 상태 확인

• AWS Management Console: CodePipeline 대시보드에서 각 액션의 상태(Success/Failed)를 확인할 수 있습니다. 실패 시 상세 오류 메시지를 클릭하면 원인(예: IAM 역할 권한 부족)이 표시됩니다.
• AWS CLI: 다음 명령어로 파이프라인 실행 기록을 조회할 수 있습니다:

aws codepipeline get-pipeline-execution-history
–pipeline-name my-pipeline
–max-results 10

> **주의**: CLI 사용 시 `AWSCodePipelineRole` 정책이 IAM 사용자/역할에 부여되어 있어야 합니다.

---

## 2. 트러블슈팅: 주요 오류 유형 및 해결 전략

### 2.1 권한 오류 (IAM Role/Policy)
**증상**: `User is not authorized to perform` 오류 발생. **원인**: IAM 역할이나 정책이 특정 AWS 서비스(예: S3, CodeBuild) 접근 권한을 누락한 경우.

**해결 방법**:
1. IAM 콘솔에서 `CodePipeline-Service-Role` 또는 `CodeBuild-Service-Role`을 선택합니다.
2. `AWSCodePipelineRole` 및 `AWSCodeBuildServiceRole` 정책이 연결되었는지 확인합니다.
3. S3 버킷 접근 권한이 필요한 경우 `AmazonS3ReadOnlyAccess`를 추가합니다.

```json
// IAM Policy 예시: S3 접근 권한 추가
{
"Version": "2012-10-17",
"Statement": [
  {
    "Effect": "Allow",
    "Action": [
      "s3:GetObject",
      "s3:PutObject"
    ],
    "Resource": "arn:aws:s3:::your-bucket-name/*"
  }
]
}

2.2 아티팩트 누락 (S3 버킷 권한)

증상: Artifact not found 오류 발생. 원인: S3 버킷 정책 또는 CodePipeline의 아티팩트 스토어 설정이 잘못된 경우.

해결 방법:

1. S3 버킷 정책에서 CodePipeline 서비스 프린시팔(codepipeline.amazonaws.com)에 s3:GetObject 및 s3:PutObject 권한을 부여합니다.
2. CodePipeline 콘솔에서 아티팩트 스토어 위치를 확인하고, 필요시 버킷을 변경합니다.

# CloudFormation 템플릿 예시: S3 버킷 정책
Resources:
  PipelineBucketPolicy:
    Type: AWS::S3::BucketPolicy
    Properties:
      Bucket: !Ref PipelineBucket
      PolicyDocument:
        Statement:
          - Effect: Allow
            Principal:
              Service: codepipeline.amazonaws.com
            Action:
              - s3:GetObject
              - s3:PutObject
            Resource: !Join ['', [!GetAtt PipelineBucket.Arn, '/*']]

2.3 빌드 스크립트 오류

증상: CodeBuild 단계에서 Command failed 오류 발생. 원인: 빌드 스크립트(예: buildspec.yml)의 문법 오류 또는 의존성 누락.

해결 방법:

1. buildspec.yml 파일을 로컬에서 테스트합니다.
2. CodeBuild 로그에서 실패한 단계를 확인합니다.
3. 필요한 경우 pip install 또는 npm install 명령어를 추가합니다.

# buildspec.yml 예시
version: 0.2
phases:
  install:
    runtime-versions:
      python: 3.9
    commands:
      - pip install -r requirements.txt
  build:
    commands:
      - python app.py test
artifacts:
  files:
    - dist/*

3. 검증 및 예방 조치

3.1 테스트 파이프라인 구축

실제 파이프라인을 변경하기 전, 테스트 브랜치를 사용해 검증 환경을 구축합니다. 예를 들어, dev 브랜치에서 파이프라인을 실행한 후 성공 시 main 브랜치로 병합하는 전략을 적용할 수 있습니다.

3.2 SNS 연동으로 실시간 알림 설정

파이프라인 실패 시 Slack 또는 이메일로 알림을 받으려면 SNS 토픽을 연동합니다.

# SNS 토픽 생성 및 CodePipeline에 연결
SNS_TOPIC_ARN=$(aws sns create-topic --name codepipeline-alerts \
  --query 'TopicArn' --output text)

aws codepipeline update-pipeline \
  --pipeline-name my-pipeline \
  --pipeline-configuration \
    '{