Container on Joonlog

컨테이너 환경에서 MTU 불일치로 인한 네트워크 타임아웃 이슈 TroubleShooting

Fri, 21 Nov 2025 09:00:00 +0900

컨테이너 환경에서 서버와 컨테이너의 MTU 불일치로 인한 네트워크 이슈를 정리한 글

환경

NCP 서버 3대
구조: Nginx 컨테이너 서버 → PHP-FPM 컨테이너 서버 → DB 서버
MariaDB 10.3

문제 상황

구축한 사이트 이용 간 아무 패턴 없이 간헐적으로 타임아웃 발생
- 이슈 발생 주기는 완전 랜덤
- 사이트 내 모든 경로에서 간헐적으로 발생
서버 리소스나 부하는 모두 정상

에러 분석

처음에는 애플리케이션 단 문제로 생각해서 점검
- 세션 분리는 이미 되어 있는 상태
- 가비지 콜렉션 설정은 없어서 GC 설정 했으나 증상 동일
DB쪽 지표 모두 정상

원인

네트워크 쪽을 점검해보니 서버와 컨테이너의 MTU가 차이가 많이 나는 것을 확인
- NCP는 서버의 기본 MTU가 8590이라고 함
- 컨테이너는 기본값 사용 중이었으니 1500
- MTU 값 불일치로 발생했던 이슈로 확인
  - 크기가 작은 요청은 정상이다가 일부 큰 패킷들이 드랍 → php 세션 끊어짐 → PHP가 요청을 끝까지 처리하지 못해서 타임아웃

해결

Docker 데몬 MTU 수정
- /etc/docker/daemon.json
  - 수정 후 docker 재기동 필요
  1 2 3
  
  { "mtu": 8950 }

컨테이너 네트워크 MTU 수정

compose의 경우 mtu 값 명시

1
2
3
4
5


networks:
 default:
 driver: bridge
 driver_opts:
 com.docker.network.driver.mtu: 8950

컨테이너 환경에서 Jenkins의 PHP CICD 파이프라인 구축하기

Thu, 20 Nov 2025 09:00:00 +0900

PHP 애플리케이션에 대한 CI/CD 파이프라인 설정 방법

환경

Git 리포지토리 및 컨테이너 레지스트리: GitLab
CI/CD: Jenkins
PHP 버전: 8.3
파이프라인을 컨테이너에서 동작시키기 위한 Jenkins Agent 도커 설정

파이프라인 설정

Git 리포지토리 연동
- Definition: Pipeline script from SCM
  - 파이프라인 구성에 필요한 스크립트를 SCM에서 가져오도록 설정
- SCM: Git
- Repository URL: Git 리포지토리 URL
- Credentials: Git 리포지토리에 접근 가능하도록 저장한 Credential
- Branch Specifier: */main

CI 파이프라인

컨테이너 이미지를 빌드하기 위한 Dockerfile도 Git 리포지토리에 있어야 함
PHP는 빌드 과정이 필요 없는 인터프리터 언어이기 때문에 소스 빌드 없이 이미지 빌드 → 이미지 푸시 과정만 필요
CI 완료 전 CD 파이프라인을 트리거

1. 환경

agent any로 jenkins agent 컨테이너를 파이프라인으로 사용

1
2
3
4
5
6
7
8
9


pipeline {
 agent any

 environment {
 APP_NAME = '<애플리케이션 명>'
 GITLAB_REGISTRY = '<컨테이너 레지스트리 URL>'
 GITLAB_PROJECT = '<Git 리포지토리 명>'
 GITLAB_CREDENTIAL_ID = '<저장한 Git PAT 토큰 ID>'
 }

2. Git 체크아웃

Git 리포지토리의 최신 커밋을 체크아웃
파이프라인 로그에 커밋 정보 출력

1
2
3
4
5
6
7


 stages {
 stage('Checkout') {
 steps {
 checkout scm
 sh 'git log -1 --oneline'
 }
 }

3. 컨테이너 이미지 빌드 및 레지스트리 푸시

Git 리포지토리에 있는 Dockerfile을 기반으로 이미지 빌드
Git 커밋 해시와 Jenkins 빌드 번호를 조합해서 태그 생성
GitLab PAT 토큰으로 로그인 후 푸시

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


 stage('Docker Build & Push') {
 steps {
 script {
 def gitCommit = sh(returnStdout: true, script: 'git rev-parse --short HEAD').trim()
 def imageTag = "${env.BUILD_NUMBER}-${gitCommit}"
 def fullImage = "${GITLAB_REGISTRY}/${GITLAB_PROJECT}/${APP_NAME}"

 sh """
 docker build --no-cache -t ${fullImage}:${imageTag} .
 docker tag ${fullImage}:${imageTag} ${fullImage}:latest
 """

 withCredentials([usernamePassword(credentialsId: "${GITLAB_CREDENTIAL_ID}",
 usernameVariable: 'GITLAB_USER',
 passwordVariable: 'GITLAB_TOKEN')]) {
 sh """
 echo "\$GITLAB_TOKEN" | docker login ${GITLAB_REGISTRY} -u "\$GITLAB_USER" --password-stdin
 docker push ${fullImage}:${imageTag}
 docker push ${fullImage}:latest
 docker logout ${GITLAB_REGISTRY}
 """
 }

 echo "Docker image pushed: ${fullImage}:${imageTag}"
 echo "Docker image pushed: ${fullImage}:latest"
 }
 }

4. CD 파이프라인 트리거

CI 파이프라인이 완료 되기 전 CD 파이프라인을 동작하도록 트리거

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


 stage('Trigger CD') {
 steps {
 build job: '<CD 파이프라인 이름>',
 parameters: [
 string(name: 'IMAGE_TAG', value: 'latest'),
 string(name: 'DEPLOY_TARGET', value: 'ALL')
 ],
 wait: true, // CD 끝날 때까지 기다릴지
 propagate: true // CD 실패하면 이 Job도 실패로 처리할지
 }
 }
 }

5. 파이프라인 결과 체크

1
2
3
4
5
6
7
8
9


 post {
 success {
 echo "Build #${env.BUILD_NUMBER} succeeded for ${APP_NAME}"
 }
 failure {
 echo "Build #${env.BUILD_NUMBER} failed - check console output"
 }
 }
}

CD 파이프라인

Jenkins 서버에서 배포할 서버에 SSH로 접근 후 docker compose 파일을 기동하여 컨테이너 레지스트리의 이미지를 가져오는 방식으로 배포
배포할 서버가 여러 개일 경우를 고려해서 구성

환경

agent any로 jenkins agent 컨테이너를 파이프라인으로 사용
DB 접속정보 등 민감한 정보가 있는 .env 파일은 Jenkins Credential로 관리

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


pipeline {
 agent any

 parameters {
 string(name: 'IMAGE_TAG', defaultValue: 'latest', description: 'Docker image tag to deploy')
 choice(name: 'DEPLOY_TARGET', choices: ['WAS1', 'ALL'], description: 'WAS1: <WAS 서버 IP> | ALL: 전체 WAS 배포')
 }

 environment {
 WAS1_HOST = '<WAS1 서버 IP>'
 // WAS2_HOST = '<WAS2 서버 IP>' // TODO: WAS2 추가 시 활성화
 DEPLOY_PATH = '<배포 경로>'
 GITLAB_REGISTRY = '<컨테이너 레지스트리 URL>'
 GITLAB_PROJECT = '<Git 리포지토리명>'
 IMAGE_NAME = '<컨테이너 이미지 명>'
 DEPLOY_CREDENTIAL_ID = '<배포 서버 SSH 계정명>'
 GITLAB_CREDENTIAL_ID = '<저장한 Git PAT 토큰 ID>'
 TEACHER_ENV_FILE_CREDENTIAL_ID = '<Credential에 저장한 .env 파일 ID>'
 COMPOSE_FILE_LOCAL = 'docker-compose.yaml'
 }

1. Git 체크아웃

파이프라인이 “Pipeline script from SCM” 으로 되어 있기 때문에 가능
docker-compose.yaml 파일을 가져오기 위함

1
2
3
4
5
6
7


 stage('Checkout') {
 steps {
 // CD Job이 Pipeline from SCM로 설정돼 있다는 전제
 checkout scm
 sh "ls -al ${COMPOSE_FILE_LOCAL} || echo 'compose 파일 경로 확인 필요'"
 }
 }

2. 준비

배포할 이미지 태그 / 배포 대상 서버를 선택할 수 있게 설정
deployHosts: 배포 대상 호스트 목록

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


 stages {
 stage('Prepare') {
 steps {
 script {
 echo "Deploying image: ${GITLAB_REGISTRY}/${GITLAB_PROJECT}/${IMAGE_NAME}:${params.IMAGE_TAG}"
 echo "Deploy target: ${params.DEPLOY_TARGET}"

 def deployHosts = []
 if (params.DEPLOY_TARGET == 'WAS1') {
 deployHosts = [WAS1_HOST]
 } else if (params.DEPLOY_TARGET == 'ALL') {
 deployHosts = [WAS1_HOST]
 // TODO: WAS2 추가 시 -> deployHosts = [WAS1_HOST, WAS2_HOST]
 }

 env.DEPLOY_HOSTS = deployHosts.join(',')
 echo "Target servers: ${env.DEPLOY_HOSTS}"
 }
 }
 }

3. 배포

컨테이너 레지스트리에서 이미지 풀링
.env 파일을 Credential에서 배포 서버로 복사
git으로 체크아웃한 docker-compose 파일을 배포 서버로 복사
배포 경로에서 docker compose 명령어를 통한 애플리케이션 재기동

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63


 stage('Deploy') {
 steps {
 script {
 def hosts = env.DEPLOY_HOSTS.split(',')

 withCredentials([
 usernamePassword(credentialsId: "${DEPLOY_CREDENTIAL_ID}",
 usernameVariable: 'DEPLOY_USER',
 passwordVariable: 'DEPLOY_PASS'),
 usernamePassword(credentialsId: "${GITLAB_CREDENTIAL_ID}",
 usernameVariable: 'GITLAB_USER',
 passwordVariable: 'GITLAB_TOKEN'),
 // .env 전체를 파일로 받음
 file(credentialsId: "${TEACHER_ENV_FILE_CREDENTIAL_ID}",
 variable: '<env 변수명>')
 ]) {
 for (host in hosts) {
 echo "Deploying to ${host}..."

 sh """
 # 0) 임시 파일 경로(충돌 방지용)
 TMP_ENV=/tmp/env.\$(date +%s)
 TMP_COMPOSE=/tmp/compose.\$(date +%s).yaml

 # 1) .env / docker-compose.yaml 둘 다 /tmp 로 복사
 sshpass -p "\$DEPLOY_PASS" scp -o StrictHostKeyChecking=no "\$<env 변수명>" "\$DEPLOY_USER"@${host}:"\$TMP_ENV"

 sshpass -p "\$DEPLOY_PASS" scp -o StrictHostKeyChecking=no "${COMPOSE_FILE_LOCAL}" "\$DEPLOY_USER"@${host}:"\$TMP_COMPOSE"

 # 2) 서버 안에서 sudo로 최종 위치로 이동 + 권한 조정 + 컨테이너 재기동
 sshpass -p "\$DEPLOY_PASS" ssh -o StrictHostKeyChecking=no "\$DEPLOY_USER"@${host} "
 echo 'Apply .env & docker-compose.yaml...'

 # .env 교체
 sudo mv \$TMP_ENV ${DEPLOY_PATH}/.env
 sudo chown nginx:nginx ${DEPLOY_PATH}/.env

 # docker-compose.yaml 교체
 sudo mv \$TMP_COMPOSE ${DEPLOY_PATH}/docker-compose.yaml
 sudo chown root:root ${DEPLOY_PATH}/docker-compose.yaml

 echo 'Logging in to GitLab Registry...'
 echo '\$GITLAB_TOKEN' | sudo docker login ${GITLAB_REGISTRY} -u '\$GITLAB_USER' --password-stdin

 echo 'Pulling image: ${GITLAB_REGISTRY}/${GITLAB_PROJECT}/${IMAGE_NAME}:${params.IMAGE_TAG}'
 sudo docker pull ${GITLAB_REGISTRY}/${GITLAB_PROJECT}/${IMAGE_NAME}:${params.IMAGE_TAG}

 echo 'Redeploying containers...'
 export IMAGE_TAG=${params.IMAGE_TAG}

 sudo docker compose -f ${DEPLOY_PATH}/docker-compose.yaml down
 sudo docker compose -f ${DEPLOY_PATH}/docker-compose.yaml up -d

 sudo docker logout ${GITLAB_REGISTRY}
 "
 """

 echo "Deployment to ${host} completed."
 }
 }
 }
 }
 }

4. 헬스 체크

배포 완료 후 컨테이너 상태 점검

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


 stage('Health Check') {
 steps {
 script {
 echo "Waiting for application to start..."
 sleep 10

 def hosts = env.DEPLOY_HOSTS.split(',')

 withCredentials([
 usernamePassword(credentialsId: "${DEPLOY_CREDENTIAL_ID}",
 usernameVariable: 'DEPLOY_USER',
 passwordVariable: 'DEPLOY_PASS')
 ]) {
 for (host in hosts) {
 echo "Health checking ${host}..."

 sh """
 sshpass -p "\$DEPLOY_PASS" ssh -o StrictHostKeyChecking=no "\$DEPLOY_USER"@${host} "
 # 컨테이너 상태 확인
 sudo docker ps | grep pj-1 || exit 1
 "
 """

 echo "${host} health check passed."
 }
 }
 }
 }
 }
 }

5. 파이프라인 결과 체크

1
2
3
4
5
6
7
8
9


 post {
 success {
 echo "Deployment succeeded - ${IMAGE_NAME}:${params.IMAGE_TAG} deployed to ${env.DEPLOY_HOSTS}"
 }
 failure {
 echo "Deployment failed - check console output"
 }
 }
}

컨테이너 환경에서 Jenkins의 Java CICD 파이프라인 구축하기

Thu, 13 Nov 2025 09:00:00 +0900

Java 1.8 애플리케이션에 대한 CI/CD 파이프라인 설정 방법

환경

Git 리포지토리 및 컨테이너 레지스트리: GitLab
CI/CD: Jenkins
Java 버전: 1.8
빌드 툴: Maven
파이프라인을 컨테이너에서 동작시키기 위한 Jenkins Agent 도커 설정

파이프라인 설정

Git 리포지토리 연동
- Definition: Pipeline script from SCM
  - 파이프라인 구성에 필요한 스크립트를 SCM에서 가져오도록 설정
- SCM: Git
- Repository URL: Git 리포지토리 URL
- Credentials: Git 리포지토리에 접근 가능하도록 저장한 Credential
- Branch Specifier: */main

CI 파이프라인

컨테이너 이미지를 빌드하기 위한 Dockerfile도 Git 리포지토리에 있어야 함
Java는 빌드 과정이 필요한 컴파일 언어이기 때문에 소스 빌드 → 이미지 빌드 → 이미지 푸시 과정이 필요

환경

agent any로 jenkins agent 컨테이너를 파이프라인으로 사용

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


pipeline {
 agent any

 environment {
 WAR_FILE = '<WAR파일명>'
 BUILD_PROFILE = '<개발/운영>'
 MAVEN_OPTS = '-Xmx1024m -XX:MaxPermSize=256m'

 // Docker & GitLab Registry settings
 DOCKER_IMAGE = '<이미지명>'
 GITLAB_REGISTRY = '<컨테이너 레지스트리 URL>'
 GITLAB_PROJECT = '<Git 리포지토리명>'
 GITLAB_CREDENTIAL_ID = '<저장한 Git PAT 토큰 ID>'
 }

소스코드 체크아웃

Git 리포지토리의 최신 커밋을 체크아웃
파이프라인 로그에 커밋 정보 출력

1
2
3
4
5
6
7


 stages {
 stage('Checkout') {
 steps {
 checkout scm
 sh 'git log -1 --oneline'
 }
 }

Maven 빌드

Maven 컨테이너를 사용해서 소스 빌드
로컬 ~/.m2 디렉토리를 컨테이너하고 공유해서 의존성 캐시 재사용

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


 stage('Build') {
 agent {
 docker {
 image 'maven:3.9.11-eclipse-temurin-8'
 args '-v $HOME/.m2:/root/.m2'
 reuseNode true
 }
 }
 steps {
 script {
 def settingsParam = fileExists('settings.xml') ? '-s settings.xml' : ''

 sh """
 mvn clean package -P ${BUILD_PROFILE} -DskipTests=true ${settingsParam} \
 -Dmaven.compiler.source=1.8 \
 -Dmaven.compiler.target=1.8
 """

 sh """
 test -f target/${WAR_FILE} || (echo "WAR file not found" && exit 1)
 ls -lh target/${WAR_FILE}
 """
 }
 }
 }

Artifact 보관

빌드 메타데이터(commit, branch, build_time)를 build.properties로 저장
산출물을 Artifacts로 아카이빙
- Jenkins 콘솔에서 바로 WAR 파일 다운로드 가능

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


 stage('Archive') {
 steps {
 script {
 def gitCommit = sh(returnStdout: true, script: 'git rev-parse --short HEAD').trim()
 def gitBranch = sh(returnStdout: true, script: 'git rev-parse --abbrev-ref HEAD').trim()
 def buildTime = sh(returnStdout: true, script: 'date "+%Y-%m-%d %H:%M:%S"').trim()

 writeFile file: 'build.properties', text: """BUILD_NUMBER=${env.BUILD_NUMBER}
BUILD_PROFILE=${BUILD_PROFILE}
GIT_COMMIT=${gitCommit}
GIT_BRANCH=${gitBranch}
BUILD_TIME=${buildTime}
"""
 }

 archiveArtifacts artifacts: "target/${WAR_FILE}, build.properties", fingerprint: true

 // WAR 파일을 workspace root로 복사 (Docker 빌드용)
 sh "cp target/${WAR_FILE} ."
 }
 }

컨테이너 이미지 빌드 및 레지스트리 푸시

Git 리포지토리에 있는 Dockerfile을 기반으로 이미지 빌드
Git 커밋 해시와 Jenkins 빌드 번호를 조합해서 태그 생성
GitLab PAT 토큰으로 로그인 후 푸시

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32


 stage('Docker Build & Push') {
 steps {
 script {
 def gitCommit = sh(returnStdout: true, script: 'git rev-parse --short HEAD').trim()
 def imageTag = "${env.BUILD_NUMBER}-${gitCommit}"
 def fullImageName = "${GITLAB_REGISTRY}/${GITLAB_PROJECT}/${DOCKER_IMAGE}"

 // Docker 이미지 빌드
 sh """
 docker build -t ${fullImageName}:${imageTag} .
 docker tag ${fullImageName}:${imageTag} ${fullImageName}:latest
 """

 // GitLab Container Registry 로그인 및 푸시
 withCredentials([usernamePassword(credentialsId: "${GITLAB_CREDENTIAL_ID}",
 usernameVariable: 'GITLAB_USER',
 passwordVariable: 'GITLAB_TOKEN')]) {
 sh """
 echo "\$GITLAB_TOKEN" | docker login ${GITLAB_REGISTRY} -u "\$GITLAB_USER" --password-stdin
 docker push ${fullImageName}:${imageTag}
 docker push ${fullImageName}:latest
 docker logout ${GITLAB_REGISTRY}
 """
 }

 echo "Docker image pushed: ${fullImageName}:${imageTag}"
 echo "Docker image pushed: ${fullImageName}:latest"
 }
 }
 }
 }
}

CD 파이프라인

Jenkins 서버에서 배포할 서버에 SSH로 접근 후 docker compose 파일을 기동하여 컨테이너 레지스트리의 이미지를 가져오는 방식으로 배포
배포할 서버가 여러 개일 경우를 고려해서 구성

환경

agent any로 jenkins agent 컨테이너를 파이프라인으로 사용

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


pipeline {
 agent any

 parameters {
 string(name: 'IMAGE_TAG', defaultValue: 'latest', description: 'Docker image tag to deploy')
 choice(name: 'DEPLOY_TARGET', choices: ['WAS1', 'ALL'], description: 'WAS1: <IP/HOSTNAME> | ALL: 전체 WAS 배포')
 }

 environment {
 WAS1_HOST = '<WAS1 서버 IP>'
 // WAS2_HOST = '<WAS2 서버 IP>' // TODO: WAS2 추가 시 활성화
 DEPLOY_PATH = '<배포 경로>'
 GITLAB_REGISTRY = '<컨테이너 레지스트리 URL>'
 GITLAB_PROJECT = '<Git 리포지토리명>'
 IMAGE_NAME = '<컨테이너 이미지 명>'
 DEPLOY_CREDENTIAL_ID = '<배포 서버 SSH 계정명>'
 GITLAB_CREDENTIAL_ID = '<저장한 Git PAT 토큰 ID>'
 }

준비

배포할 이미지 태그 / 배포 대상 서버를 선택할 수 있게 설정
deployHosts: 배포 대상 호스트 목록

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


 stages {
 stage('Prepare') {
 steps {
 script {
 echo "Deploying image: ${GITLAB_REGISTRY}/${GITLAB_PROJECT}/${IMAGE_NAME}:${params.IMAGE_TAG}"
 echo "Deploy target: ${params.DEPLOY_TARGET}"

 def deployHosts = []
 if (params.DEPLOY_TARGET == 'WAS1') {
 deployHosts = [WAS1_HOST]
 } else if (params.DEPLOY_TARGET == 'ALL') {
 deployHosts = [WAS1_HOST]
 // TODO: WAS2 추가 시 -> deployHosts = [WAS1_HOST, WAS2_HOST]
 }

 env.DEPLOY_HOSTS = deployHosts.join(',')
 echo "Target servers: ${env.DEPLOY_HOSTS}"
 }
 }
 }

배포

컨테이너 레지스트리에서 이미지 풀링
배포 경로에서 docker compose 명령어를 통한 애플리케이션 재기동

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49


 stage('Deploy') {
 steps {
 script {
 def hosts = env.DEPLOY_HOSTS.split(',')

 withCredentials([
 usernamePassword(credentialsId: "${DEPLOY_CREDENTIAL_ID}",
 usernameVariable: 'DEPLOY_USER',
 passwordVariable: 'DEPLOY_PASS'),
 usernamePassword(credentialsId: "${GITLAB_CREDENTIAL_ID}",
 usernameVariable: 'GITLAB_USER',
 passwordVariable: 'GITLAB_TOKEN')
 ]) {
 for (host in hosts) {
 echo "Deploying to ${host}..."

 sh """
 sshpass -p "\$DEPLOY_PASS" ssh -o StrictHostKeyChecking=no \$DEPLOY_USER@${host} "
 cd ${DEPLOY_PATH}

 # GitLab Registry 로그인
 echo 'Logging in to GitLab Registry...'
 echo "\$GITLAB_TOKEN" | sudo docker login ${GITLAB_REGISTRY} -u "\$GITLAB_USER" --password-stdin

 # 이미지 Pull
 echo 'Pulling image: ${GITLAB_REGISTRY}/${GITLAB_PROJECT}/${IMAGE_NAME}:${params.IMAGE_TAG}'
 sudo docker pull ${GITLAB_REGISTRY}/${GITLAB_PROJECT}/${IMAGE_NAME}:${params.IMAGE_TAG}

 # 컨테이너 재배포
 echo 'Redeploying containers...'
 export IMAGE_TAG=${params.IMAGE_TAG}
 sudo docker compose down
 sudo docker compose up -d

 # 배포 확인
 echo 'Checking deployment status...'
 sudo docker compose ps

 # 로그아웃
 sudo docker logout ${GITLAB_REGISTRY}
 "
 """

 echo "Deployment to ${host} completed."
 }
 }
 }
 }
 }

헬스 체크

배포 완료 후 컨테이너 상태 점검

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32


 stage('Health Check') {
 steps {
 script {
 echo "Waiting for application to start..."
 sleep 10

 def hosts = env.DEPLOY_HOSTS.split(',')

 withCredentials([usernamePassword(credentialsId: "${DEPLOY_CREDENTIAL_ID}",
 usernameVariable: 'DEPLOY_USER',
 passwordVariable: 'DEPLOY_PASS')]) {
 for (host in hosts) {
 echo "Health checking ${host}..."

 sh """
 sshpass -p "\$DEPLOY_PASS" ssh -o StrictHostKeyChecking=no \$DEPLOY_USER@${host} "
 # 컨테이너 상태 확인
 sudo docker ps | grep main

 # 헬스체크 (옵션)
 # curl -f http://localhost:8080/health || exit 1
 "
 """

 echo "${host} health check passed."
 }
 }
 }
 }
 }
 }
}

Jenkins Agent를 Docker로 동작시키기 위한 방법

Mon, 27 Oct 2025 09:00:00 +0900

Jenkins Agent가 도커로 사용되도록 설정 Jenkins Server-Agent 분리

Built-In-Node excutor 설정
- Jenkins Agent를 도커에서 동적으로 실행할거라 built-in-node의 Number of executors값을 0으로 설정
Agent Node 추가
- Manage Jenkins - Nodes - System Configuration - New Node
- Node 설정
  - Number of excutors: Jenkins Agent가 최대로 실행 가능한 파이프라인 수
  - Remote root directory: Jenkins Agent 컨테이너 내부의 루트 디렉토리
Agent 설치 스크립트 확인
- 이후에 컨테이너 기동에 필요한 secret 값이 포함되어 있으니 확인 필수

Dockerfile

파이프라인용 에이전트이므로 최소로 컨테이너 기동

1
2
3
4
5
6


FROM jenkins/inbound-agent:latest-jdk21
USER root
RUN apt-get update \
 && apt-get install -y docker.io ca-certificates openssh-client \
 && rm -rf /var/lib/apt/lists/*
USER jenkins

docker-compose.yaml

변수들은 .env 파일을 통해 별도로 설정
- JENKINS_URL: 도커 네트워크 인터페이스 docker0의 ip인 172.17.0.1를 기입
- JENKINS_SECRET: 위 콘솔에 나온 secret 값을 기입
- JENKINS_AGENT_NAME: 위에서 설정한 이름
- JENKINS_AGENT_WORKDIR: 위에서 설정한 Jenkins Agent가 컨테이너 내부에서 사용할 경로
- AGENT_WORKDIR: Jenkins Agent 컨테이너가 호스트에서 사용하는 실제 경로

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


version: "3.8"

services:
 agent:
 build:
 context: .
 dockerfile: Dockerfile
 container_name: jenkins-agent-docker
 restart: unless-stopped
 init: true
 environment:
 JENKINS_URL: "${JENKINS_URL}"
 JENKINS_SECRET: "${JENKINS_SECRET}"
 JENKINS_AGENT_NAME: "${JENKINS_AGENT_NAME}"
 JENKINS_AGENT_WORKDIR: "${JENKINS_AGENT_WORKDIR:-/home/jenkins/agent}"
 DOCKER_BUILDKIT: "1"
 JENKINS_WEB_SOCKET: "true"
 volumes:
 - /var/run/docker.sock:/var/run/docker.sock
 - ${AGENT_WORKDIR:-/var/lib/jenkins_agent}:${JENKINS_AGENT_WORKDIR:-/home/jenkins/agent}
 group_add:
 - "${DOCKER_GID}"

컨테이너 권한 설정
- 호스트의 도커 소켓을 사용하는 DooD 방식이기 때문에 컨테이너에서도 호스트의 도커 GID 동기화 필요
  - /var/lib/jenkins_agent: 호스트에 컨테이너 데이터가 저장될 경로.
    - 컨테이너 내부에서도 기록해야하니 기본 사용자인 1000으로 설정
1 2

echo "DOCKER_GID=$(stat -c %g /var/run/docker.sock)" >> .env mkdir -p /var/lib/jenkins_agent && chown 1000:1000 /var/lib/jenkins_agent
Jenkins Agent 빌드
1

docker compose up -d --build
Node 연결 확인
파이프라인 테스트
- hello world 테스트 성공!

참고

Jenkins Agent 노드 추가: https://github.com/jenkinsci/docker-agent/blob/master/README_inbound-agent.md

Pokerogue 게임을 Container 이미지로 빌드하기 위한 방법

Sun, 19 Oct 2025 09:00:00 +0900

Pokerogue 이미지 빌드

Pokerogue 게임을 컨테이너 이미지로 빌드하기 위한 방법

개요

Pokerogue 게임을 K8S 환경에서 동작하게 하기 위해서 약간의 소스코드 수정과 Dockerfile 작성이 필요
- 공식 GitHub에는 로컬 기준으로 코드가 작성된 부분이 많음
Pokerogue는 Vite 기반 React 프론트엔드와 Go 기반 백엔드 그리고 Mariadb로 구성

Frontend

공식 GitHub: https://github.com/pagefaultgames/pokerogue
TypeScript로 작성
Vite 번들러를 사용하는 React SPA
Pokerogue의 UI, 정적파일, 로직 및 랜더링 제공
/api/*로 백엔드 API 호출
OAuth 외부 로그인 UI 제공

Frontend 이미지 빌드

Dockerfile

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


ARG NODE_VERSION=22.14
ARG OS=alpine

# Build stage
FROM node:${NODE_VERSION}-${OS} AS build

RUN apk add --no-cache git rsync
WORKDIR /app

RUN corepack enable && corepack prepare pnpm@10.14.0 --activate

COPY . .

# Initialize git submodules
RUN git submodule update --init --recursive

# Install dependencies with cache
RUN --mount=type=cache,target=/root/.pnpm-store \
 pnpm install --frozen-lockfile

# Production build
RUN pnpm run build

# Production stage
FROM nginx:alpine

COPY nginx.conf /etc/nginx/conf.d/default.conf

# Copy built files from build stage
COPY --from=build /app/dist /usr/share/nginx/html

EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

공식 GitHub에는 beta 브랜치에만 Dockerfile이 존재
- development mode로 실행되게 작성되어 있어서 Dockerfile은 새로 전부 작성

Build Stage와 Production Stage 분리
- Build Stage
  - Node.js 정적 파일 빌드
  - Git submodule 초기화
  - pnpm dependencies 설치
  - pnpm 빌드로 /app/dist 생성
- Production Stage
  - Nginx Alpine 이미지
  - 빌드된 정적 파일만 복사
  - Node.js 런타임 포함하지 않음
Git Submodule 처리
- Pokerogue는 assets와 locales를 Git submodule로 관리
- 최종 이미지에는 빌드된 dist 포함되므로 빌드에 사용된 .git은 제외됨

Nginx 사용

SPA 라우팅
- https://pokerogue.com/ 이외에 /game, /home 등 제공하지 않는 경로로 접근 시 index.html을 제공하도록 설정
gzip 압축
- JavaScript, CSS 파일들을 gzip으로 압축하여 전송
보안 헤더 적용
정적 파일 캐싱
- 이미지, 폰트, JS, CSS 등을 1년간 브라우저 캐시

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


server {
 listen 80;
 server_name localhost;
 root /usr/share/nginx/html;
 index index.html;

 # SPA routing - all routes go to index.html
 location / {
 try_files $uri $uri/ /index.html;
 }

 gzip on;
 gzip_vary on;
 gzip_min_length 1024;
 gzip_types text/plain text/css text/xml text/javascript application/x-javascript application/xml+rss application/json application/javascript;

 add_header X-Frame-Options "SAMEORIGIN" always;
 add_header X-Content-Type-Options "nosniff" always;
 add_header X-XSS-Protection "1; mode=block" always;

 location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
 expires 1y;
 add_header Cache-Control "public, immutable";
 }
}

.env 파일 관리

환경변수들을 빌드 시점에 포함시켜야함

.dockeringnore 파일에 명시되어 있던 .env 주석처리

1
2
3
4
5
6
7


# .dockerignore
node_modules
*.log
*.md
.gitignore
Dockerfile
#.env 

Vite의 .env 우선순위
- Vite는 다음 순서로 .env 파일 로드
  - 나중에 로드된 파일이 이전 파일의 변수값을 덮어씀
  1. .env - 모든 환경에서 로드
  2. .env.[mode] - 특정 모드 (예: .env.production)
- 따라서 pnpm run build 실행 시 production 모드로 실행되므로 최종적으로 .env.production에 있는 환경변수를 참조하게 됨

.env | .env.production

VITE_SERVER_URL: 실제 게임을 서비스할 도메인으로 변경
VITE_DISCORD_CLIENT_ID: Discord OAuth 로그인을 위한 본인 값 입력
VITE_GOOGLE_CLIENT_ID: Google OAuth 로그인을 위한 본인 값 입력

1
2
3
4
5
6


VITE_BYPASS_LOGIN=0
VITE_BYPASS_TUTORIAL=0
VITE_SERVER_URL=https://pokerogue.<도메인>:<포트>/api
VITE_DISCORD_CLIENT_ID=<discord client id>
VITE_GOOGLE_CLIENT_ID=<google client id>
VITE_I18N_DEBUG=0

이미지 빌드

1
2


docker build -t ksi05298/pokerogue-web:latest .
docker push ksi05298/pokerogue-web:latest

Backend

공식 GitHub: https://github.com/pagefaultgames/rogueserver
Go로 작성
사용자 인증, 게임 데이터 저장, 조회, 세션 관리 등을 수행하는 RESTFUL API 서버
- /account/*, /gamedata/*, /auth/* 엔드포인트 제공
MariaDB와 연동

Backend 이미지 빌드

Dockerfile

Dockerfile은 공식 GitHub에 있는 파일 그대로 사용
- scratch 이미지를 사용해서 정적 바이너리만 포함

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


# SPDX-FileCopyrightText: 2024-2025 Pagefault Games
#
# SPDX-License-Identifier: AGPL-3.0-or-later
ARG GO_VERSION=1.22

FROM docker.io/library/golang:${GO_VERSION} AS builder

WORKDIR /src

COPY ./go.mod /src/
COPY ./go.sum /src/

RUN go mod download && go mod verify

COPY . /src/

RUN CGO_ENABLED=0 \
 go build -tags=devsetup -o rogueserver

RUN chmod +x /src/rogueserver

# ---------------------------------------------

FROM scratch

WORKDIR /app

COPY --from=builder /src/rogueserver .
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/

EXPOSE 8001

ENTRYPOINT ["./rogueserver"]

OAuth 쿠키 설정 수정

공식 rogueserver 코드에서 구글/디스코드 로그인에 필요한 OAuth 쿠키 설정에 문제 있어 수정 필요

api/endpoints.go 파일의 658줄 handleProviderCallback 함수 내부

수정 전

1
2
3
4
5
6
7
8
9


 http.SetCookie(w, &http.Cookie{
 Name: "pokerogue_sessionId",
 Value: sessionToken,
 Path: "/",
 Secure: true,
 SameSite: http.SameSiteStrictMode,
 Domain: "pokerogue.net",
 Expires: time.Now().Add(time.Hour * 24 * 30 * 3), // 3 months
 })

수정 후

1
2
3
4
5
6
7
8
9


 http.SetCookie(w, &http.Cookie{
 Name: "pokerogue_sessionId",
 Value: sessionToken,
 Path: "/",
 Secure: true,
 SameSite: http.SameSiteLaxMode,
 Domain: "",
 Expires: time.Now().Add(time.Hour * 24 * 30 * 3), // 3 months
 })

변경 사항
- SameSite: SameSiteStrictMode → SameSiteLaxMode
  - OAuth callback은 cross-site 요청이 될 수 밖에 없음 (google.com → 내 도메인)
  - Strict로 설정하면 cross-site 쿠키 전송이 차단돼서 CSRF오류가 발생됨
  - Lax로 변경하여 안전한 도메인에서의 GET 요청(oauth callback)에서 쿠키 전송 허용
- Domain: “pokerogue.net” → “”
  - pokerogue 공식 도메인에서 빈 문자열로 변경해서 현재 도메인이 자동 적용되도록 설정

이미지 빌드 및 푸시

1
2


docker build -t ksi05298/rogueserver:latest .
docker push ksi05298/rogueserver:latest

참고

Vite 환경변수 가이드:

https://vitejs.dev/guide/env-and-mode.html

OAuth SameSite Cookie 설정:

https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite

Docker Tomcat에서 Context Path 설정 무시 TroubleShooting

Sat, 04 Oct 2025 09:00:00 +0900

IDE 환경에서는 잘 작동하던 Context Path 설정이 Docker Tomcat에서는 무시되어 발생한 문제 Tomcat의 WAR 파일 배포 메커니즘과 appBase/docBase 개념을 이해해야 해결 가능한 이슈

환경

Java 1.8
Tomcat 9.0.41
Spring 기반 CMS
Docker로 Tomcat WAS 구성

문제 상황

빌드한 app.war를 Docker Tomcat으로 배포 후 /app/index.do 접근 시 무한 리다이렉트 발생
- /app/index.do → /index.html → /app/index.do 반복
context path가 /로 설정됐어야 하는데 app으로 설정되어 있음
- server.xml 설정이 무시됨

초기 설정

Dockerfile

1
2


COPY app.war ${CATALINA_HOME}/webapps/app.war
COPY server.xml ${CATALINA_HOME}/conf/server.xml

server.xml

1
2
3
4


<Host name="localhost" appBase="webapps"
 unpackWARs="true" autoDeploy="true">
 <Context path="" docBase="app" reloadable="false" />
</Host>

에러 분석

무한 리다이렉트 발생 이유
- 애플리케이션에 index.do를 받을 수 있는 2개의 컨트롤러 존재
  1. @RequestMapping("/index.do")
    - index.html로 리다이렉트
  2. @RequestMapping("/{siteId}/index.do")
    - 실제 사이트 로직 처리
- 브라우저에서 /app/index.do로 접근 시 2번으로 가야하는데 계속 1번으로만 처리됨
  - context path가 /가 아닌 app으로 되어 있다는 증거
    1. /app/index.do로 요청
    2. Tomcat이 context path 제거 → Servlet Path = /index.do
    3. Spring이 /index.do 매핑 찾음 → 1번 컨트롤러 매칭
    4. redirect:/index.html 반환
    5. /index.html 내부에 location.href = "/app/index.do" 스크립트
    6. 1번으로 돌아가서 무한 루프
server.xml 설정이 무시된 이유
- Tomcat의 WAR 배포 우선순위
  1. autoDeploy="true" 설정 시 webapps 디렉토리 자동 스캔
  2. app.war 발견 → 파일명 기준으로 자동 배포
    - Context Path = /app
  3. server.xml의 <Context> 설정은 자동 배포에 의해 무시됨
IDE 환경과의 차이가 발생한 이유
- IDE
  1. UI에서 Context Path를 /로 직접 지정 가능
  2. WAR 파일명과 무관하게 IDE 내부적으로 Context 설정 파일 생성
- Docker Tomcat
  1. WAR 파일명이 Context Path를 결정
  2. Tomcat 자체 규칙만 적용

해결 방법 1

war 파일을 ROOT.war로 배포
- 가장 간단하고 확실한 방법
- Context Path가 ROOT.war 파일명에 따라 /로 설정됨
- Dockerfile
  1
  
  COPY app.war ${CATALINA_HOME}/webapps/ROOT.war
1. /app/index.do로 요청
2. Tomcat이 context path 제거 → Servlet Path = /app/index.do
3. Spring이 /{siteId}/index.do 패턴 매칭 → 2번 컨트롤러 매칭 (siteId=app)
4. 정상 동작

해결 방법 2

Context xml 파일 설정

app.war 파일명을 유지하면서 Context Path를 변경하는 방법
appBase: Tomcat이 애플리케이션을 찾는 작업 공간
- 기본: webapps
docBase: 특정 애플리케이션의 실제 파일 위치

Tomcat 9 보안 정책: appBase 내부의 WAR를 docBase로 지정하면 무시됨

war 파일을 appBase와 다른곳으로 이동

Dockerfile

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# WAR를 appBase 밖에 배치
RUN mkdir -p ${CATALINA_HOME}/apps
COPY app.war ${CATALINA_HOME}/apps/app.war

# Context 설정 파일 생성
RUN mkdir -p ${CATALINA_HOME}/conf/Catalina/localhost
COPY ROOT.xml ${CATALINA_HOME}/conf/Catalina/localhost/ROOT.xml

# server.xml 수정 (autoDeploy 비활성화)
COPY server.xml ${CATALINA_HOME}/conf/server.xml

ROOT.xml

1
2


<?xml version="1.0" encoding="UTF-8"?>
<Context docBase="${catalina.home}/apps/app.war" />

server.xml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


<?xml version="1.0" encoding="UTF-8"?>
<Server port="8005" shutdown="SHUTDOWN">
 <Service name="Catalina">
 <Connector port="8080" protocol="HTTP/1.1"
 connectionTimeout="20000"
 redirectPort="8443"
 URIEncoding="UTF-8" />

 <Engine name="Catalina" defaultHost="localhost">
 <Host name="localhost" appBase="webapps"
 unpackWARs="true" autoDeploy="false" deployOnStartup="true">
 </Host>
 </Engine>
 </Service>
</Server>

동작 순서
1. server.xml의 autoDeploy="false" 설정으로 webapps의 WAR자동 배포 비활성화
2. server.xml의 deployOnStartup="true" 설정으로 Context XML 파일 읽기 활성화
3. ROOT.xml → Context Path / 지정
  - 파일명이 ROOT이므로 /로 설정됨
4. ROOT.xml의 docBase="/opt/tomcat/apps/app.war" 설정으로 appBase 밖의 경로에서 war참조
5. Tomcat이 apps/app.war를 webapps/ROOT/로 압축 해제 후 실행
6. 정상 동작

정리

Tomcat의 WAR 배포 규칙

WAR 파일명: Context Path

1
2
3


ROOT.war -> /
admin.war -> /admin
my-app.war -> /my-app

server.xml의 Context 설정은 비권장
- autoDeploy="true" 환경에서는 대부분 무시됨
- 설정 변경 시 Tomcat 전체 재시작 필요
appBase / docBase

appBase 내부의 WAR를 docBase로 지정하면 Tomcat 9에서 무시됨

항목 appBase docBase

정의 Tomcat의 작업 공간 앱의 소스 위치

기본값 webapps -

내용 WAR + 압축 해제된 코드 WAR 또는 디렉토리 경로

자동 배포 O X
Context Path / Servlet Path

애플리케이션 라우팅 로직이 Servlet Path를 기준으로 설계되었다면 Context Path가 라우팅에 영향을 줄 수 있음
- 요청 URL: /app/index.do
  1 2
  
  Context Path: / Servlet Path: /app/index.do
- 요청 URL: /app/index.do
  1 2
  
  Context Path: /app Servlet Path: /index.do

항목	appBase	docBase
정의	Tomcat의 작업 공간	앱의 소스 위치
기본값	`webapps`	-
내용	WAR + 압축 해제된 코드	WAR 또는 디렉토리 경로
자동 배포	O	X

참고

Containerd 설치 및 환경 세팅하기

Fri, 05 Sep 2025 09:00:00 +0900

containerd만 단독으로 설치 했을 경우 CRI의 기능만 제공하며, docker처럼 기능을 사용하기 위해선 플러그인 설치가 필요

containerd 설치

1
2
3
4


for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do sudo dnf remove $pkg -y; done
dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
dnf install -y containerd.io
containerd config default | sudo tee /etc/containerd/config.toml

containerd 디렉토리 설정(선택)

1
2
3
4
5
6
7
8


### containerd root 디렉토리 외에 data 디렉토리에서 동작하도록 설정
sed -i 's|^root = .*|root = "/data/container/containerd"|' /etc/containerd/config.toml
sed -i 's|^state = .*|state = "/data/container/containerd-state"|' /etc/containerd/config.toml
mkdir -p /data/container/containerd
mkdir -p /data/container/containerd-state
mkdir -p /data/container/nerdctl
echo 'export NERDCTL_DATA_ROOT=/data/container/nerdctl' >> ~/.bashrc
source ~/.bashrc

nerdctl 설치

도커 명령어처럼 containerd를 관리하기 위한 툴
- ex) nerdctl ps -a, nerdctl images

1
2
3
4


# nerdctl 설치
wget https://github.com/containerd/nerdctl/releases/download/v0.17.0/nerdctl-0.17.0-linux-amd64.tar.gz
tar Cxzvvf /usr/bin nerdctl-0.17.0-linux-amd64.tar.gz
echo "source <(nerdctl completion bash)" >> ~/.bashrc

CNI 설치

컨테이너 네트워크를 관리하기 위한 툴
- 컨테이너의 ip 등의 네트워크를 지정해서 설정 가능

1
2
3
4


# CNI 설치
wget https://github.com/containernetworking/plugins/releases/download/v1.0.1/cni-plugins-linux-amd64-v1.0.1.tgz
mkdir -p /opt/cni/bin
tar Cxzvvf /opt/cni/bin cni-plugins-linux-amd64-v1.0.1.tgz

buildkit 설치

containerd에서 image를 빌드하기 위한 툴

1
2
3


wget https://github.com/moby/buildkit/releases/download/v0.10.0-rc1/buildkit-v0.10.0-rc1.linux-amd64.tar.gz
tar Cxzvvf /usr/bin buildkit-v0.10.0-rc1.linux-amd64.tar.gz
nohup /usr/bin/builkitd < /dev/null > /var/log/buildkitd 2>&1 &

containerd 실행
1

systemctl enable --now containerd

Linux 환경에서 Docker 설치 (RedHat/Ubuntu 계열)

Mon, 01 Sep 2025 09:00:00 +0900

https://docs.docker.com/engine/install

RedHat 계열

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


# 기존 설치되어있는 컨테이너 런타임 삭제
for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do sudo dnf remove $pkg -y; done

# docker repo 추가
yum install -y yum-utils
yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
# docker 설치
yum install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 현재 사용자를 docker 그룹에 추가해서 root 권한 없어도 docker 사용 가능하게 설정
usermod -a -G docker <user>

systemctl enable --now docker

Ubuntu 계열

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


# 기존 설치되어있는 컨테이너 런타임 삭제
for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do sudo apt-get remove $pkg; done

# docker repo 설정
apt-get update
apt-get install ca-certificates curl
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc
# docker repo 추가
echo \
 "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
 $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
 sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

# docker 설치
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 현재 사용자를 docker 그룹에 추가해서 root 권한 없어도 docker 사용 가능하게 설정
usermod -a -G docker <user>

systemctl enable --now docker

Cacti Conainer 구축

Wed, 30 Jul 2025 09:00:00 +0900

Containerd 사용

Git 소스 코드

1
2


dnf install -y git-all
git clone https://github.com/scline/docker-cacti.git

Containerd 환경 구축

https://containerd.io/downloads/ 여기서 다운로드도 가능

https://medium.com/@DannielWhatever/using-containerd-without-docker-9d08332781b4

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do sudo dnf remove $pkg -y; done
dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
dnf install -y containerd.io
containerd config default | sudo tee /etc/containerd/config.toml

### containerd root 디렉토리 외에 data 디렉토리에서 동작하도록 설정
sed -i 's|^root = .*|root = "/data/container/containerd"|' /etc/containerd/config.toml
sed -i 's|^state = .*|state = "/data/container/containerd-state"|' /etc/containerd/config.toml
mkdir -p /data/container/containerd
mkdir -p /data/container/containerd-state
mkdir -p /data/container/nerdctl
echo 'export NERDCTL_DATA_ROOT=/data/container/nerdctl' >> ~/.bashrc
source ~/.bashrc

# nerdctl 설치
wget https://github.com/containerd/nerdctl/releases/download/v0.17.0/nerdctl-0.17.0-linux-amd64.tar.gz
tar Cxzvvf /usr/bin nerdctl-0.17.0-linux-amd64.tar.gz
echo "source <(nerdctl completion bash)" >> ~/.bashrc

# CNI 설치
wget https://github.com/containernetworking/plugins/releases/download/v1.0.1/cni-plugins-linux-amd64-v1.0.1.tgz
mkdir -p /opt/cni/bin
tar Cxzvvf /opt/cni/bin cni-plugins-linux-amd64-v1.0.1.tgz

# buildkit 설치
wget https://github.com/moby/buildkit/releases/download/v0.10.0-rc1/buildkit-v0.10.0-rc1.linux-amd64.tar.gz
tar Cxzvvf /usr/bin buildkit-v0.10.0-rc1.linux-amd64.tar.gz
nohup /usr/bin/builkitd < /dev/null > /var/log/buildkitd 2>&1 &

systemctl enable --now containerd

Cacti Container 구조

cacti master와 master용 DB
cacti poller와 poller용 DB

docker-compose-master.yaml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73


version: '3.5'

services:
 cacti-master:
 image: "smcline06/cacti"
 container_name: cacti_master
 hostname: cactimaster
 depends_on:
 - db-master
 ports:
 - "80:80"
 - "443:443"
 environment:
 - DB_NAME=cacti_master
 - DB_USER=cactiuser
 - DB_PASS=cactipassword
 - DB_HOST=db-master
 - DB_PORT=3306
 - DB_ROOT_PASS=rootpassword
 - INITIALIZE_DB=1
 - TZ=Asia/Seoul
 volumes:
 - cacti-master-data:/cacti
 - cacti-shared-rra:/cacti/rra
 - cacti-master-spine:/spine
 - cacti-master-backups:/backups
 networks:
 - cacti-net

 db-master:
 image: "mariadb:10.3"
 container_name: cacti_master_db
 hostname: db-master
 ports:
 - "3306:3306"
 command:
 - mysqld
 - --character-set-server=utf8mb4
 - --collation-server=utf8mb4_unicode_ci
 - --max_connections=200
 - --max_heap_table_size=128M
 - --max_allowed_packet=32M
 - --tmp_table_size=128M
 - --join_buffer_size=128M
 - --innodb_buffer_pool_size=1G
 - --innodb_doublewrite=ON
 - --innodb_flush_log_at_timeout=3
 - --innodb_read_io_threads=32
 - --innodb_write_io_threads=16
 - --innodb_buffer_pool_instances=9
 - --innodb_file_format=Barracuda
 - --innodb_large_prefix=1
 - --innodb_io_capacity=5000
 - --innodb_io_capacity_max=10000
 environment:
 - MYSQL_ROOT_PASSWORD=rootpassword
 - TZ=Asia/Seoul
 volumes:
 - cacti-db-master:/var/lib/mysql
 networks:
 - cacti-net

volumes:
 cacti-db-master:
 cacti-master-data:
 cacti-shared-rra:
 cacti-master-spine:
 cacti-master-backups:

networks:
 cacti-net:
 name: cacti-net
 external: true

docker-compose-poller.yaml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80


version: '3.5'

services:
 cacti-poller:
 image: "smcline06/cacti"
 container_name: cacti_poller
 hostname: cactipoller
 depends_on:
 - db-poller
 ports:
 - "8080:80"
 - "8443:443"
 environment:
 - DB_NAME=cacti_poller
 - DB_USER=cactipolleruser
 - DB_PASS=cactipollerpassword
 - DB_HOST=db-poller
 - DB_PORT=3306
 - RDB_NAME=cacti_master
 - RDB_USER=cactiuser
 - RDB_PASS=cactipassword
 - RDB_HOST=db-master
 - RDB_PORT=3306
 - DB_ROOT_PASS=rootpassword
 - REMOTE_POLLER=1
 - INITIALIZE_DB=1
 - TZ=Asia/Seoul
 volumes:
 - cacti-poller-data:/cacti
 - cacti-shared-rra:/cacti/rra
 - cacti-poller-spine:/spine
 - cacti-poller-backups:/backups

 networks:
 - cacti-net

 db-poller:
 image: "mariadb:10.3"
 container_name: cacti_poller_db
 hostname: db-poller
 command:
 - mysqld
 - --character-set-server=utf8mb4
 - --collation-server=utf8mb4_unicode_ci
 - --max_connections=200
 - --max_heap_table_size=128M
 - --max_allowed_packet=32M
 - --tmp_table_size=128M
 - --join_buffer_size=128M
 - --innodb_buffer_pool_size=1G
 - --innodb_doublewrite=ON
 - --innodb_flush_log_at_timeout=3
 - --innodb_read_io_threads=32
 - --innodb_write_io_threads=16
 - --innodb_buffer_pool_instances=9
 - --innodb_file_format=Barracuda
 - --innodb_large_prefix=1
 - --innodb_io_capacity=5000
 - --innodb_io_capacity_max=10000
 environment:
 - MYSQL_ROOT_PASSWORD=rootpassword
 - TZ=Asia/Seoul
 volumes:
 - cacti-db-poller:/var/lib/mysql
 networks:
 - cacti-net

volumes:
 cacti-db-poller:
 cacti-poller-data:
 cacti-shared-rra:
 name: containerd-cacti_cacti-shared-rra
 external: true
 cacti-poller-spine:
 cacti-poller-backups:

networks:
 cacti-net:
 name: cacti-net
 external: true

cacti-net CNI

ip 지정해서 쓰기 위한 사전 세팅

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44


cat <<EOF > /etc/cni/net.d/cacti-net.conflist
{
 "cniVersion": "0.4.0",
 "name": "cacti-net",
 "nerdctlID": 2,
 "nerdctlLabels": {
 "com.docker.compose.network": "cacti-net",
 "com.docker.compose.project": "cacti"
 },
 "plugins": [
 {
 "type": "bridge",
 "bridge": "cactibr0",
 "isGateway": true,
 "ipMasq": true,
 "ipam": {
 "type": "host-local",
 "ranges": [
 [
 {
 "subnet": "10.99.0.0/24",
 "gateway": "10.99.0.1"
 }
 ]
 ],
 "routes": [
 { "dst": "0.0.0.0/0" }
 ]
 }
 },
 {
 "type": "portmap",
 "capabilities": { "portMappings": true }
 },
 {
 "type": "firewall"
 },
 {
 "type": "tuning"
 }
 ]
}

EOF

cacti 컨테이너 실행

1
2
3
4
5


nerdctl compose -f docker-compose-master.yaml up -d
nerdctl compose -f docker-compose-poller.yaml up -d

# netstat으로 port 확인 안됨
iptables -t nat -L -n -v

SNMP 체크

1

snmpwalk -v2c -c public <ip>:<port> system

Cacti Conainer의 Script Tools

Tue, 29 Jul 2025 09:00:00 +0900

Backup

백업
1

docker exec <docker image ID or name> ./backup.sh
- 루트 Cacti/Spine 디렉토리 복사 및 cacti DB 덤프 수행
- cacti container의 /backups 디렉토리 아래에 tar.gz 형식으로 압축 백업 저장
- BACKUP_RETENTION 값 조정. 기본값 7개

백업 복원

1

docker exec <docker image ID or name> ./restore.sh /backups/<filename>

백업 목록 조회

1

docker exec <docker image ID or name> ls /backups

Update

1

docker exec <docker image ID or name> ./upgrade.sh

버전 지정 시 upgrade.sh 수정
- Cacti Version Links
- Spine Version Links

Template

시작 시 스크립트가 가져와서 설치됨

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


├── templates
│ ├── template_name.xml
│ ├── resource
│ │ └── script_queries
│ │ └── ...
│ │ └── script_server
│ │ └── ...
│ │ └── snmp_queries
│ │ └── ...
│ ├── scripts
│ │ └── ...

Plugins

plugins 디렉토리에 플러그인을 넣는 것으로 부팅 시 자동 로드
Cacti GUI에서 플러그인 활성화 필요
컨테이너 동작 후 플러그인 추가하려면 docker volume을 통해 마운트 필요

Settings

sql 변경사항을 settings 디렉토리 아래에 배치하여 초기 설치 시 설정 가능

start.sh가 설치 시 모든 *.sql을 병합하기 때문

ex) settings/spine.sql은 spine 활성화하기 위한 sql

1
2
3
4
5
6
7


--
-- Enable spine poller from docker installation
--

REPLACE INTO `%DB_NAME%`.`settings` (`name`, `value`) VALUES('path_spine', '/spine/bin/spine');
REPLACE INTO `%DB_NAME%`.`settings` (`name`, `value`) VALUES('path_spine_config', '/spine/etc/spine.conf');
REPLACE INTO `%DB_NAME%`.`settings` (`name`, `value`) VALUES('poller_type', '2');

Cacti Conainer 환경변수

Mon, 28 Jul 2025 09:00:00 +0900

Cacti Master

환경 변수	기능
DB_NAME	MySQL DB 이름. Cacti, Spine Poller 공유
DB_USER	MySQL DB 사용자. Cacti, Spine Poller 공유
DB_PASS	MySQL DB 비밀번호. Cacti, Spine Poller 공유
DB_HOST	DB IP/FQDN/호스트/컨테이너이름
DB_PORT	MySQL DB 포트. 기본값 3306
DB_ROOT_PASS	`INITIALIZE_DB`가 1로 설정된 경우 필요
INITIALIZE_DB	`0: false` / `true: 1`. true면 컨테이너는 대상 데이터베이스에 대한 `DB_ROOT_PASS`를 요구. DB 초기화 설정
TZ	타임존 설정
BACKUP_RETENTION	보관할 백업 파일의 수
REMOTE_POLLER	`0: false` / `true: 1`
PHP_MEMORY_LIMIT	PHP 메모리 제한 조정, 기본값은 128M
PHP_MAX_EXECUTION_TIME	PHP 최대 실행 시간 조정, 기본값은 30초
PHP_SNMP	0으로 설정하면 PHP-SNMP 제거. 기본값은 php-snmp 활성화. 일부 스크립트나 snmpv3가 제대로 동작하기 위해 필요

Cacti Pollers

환경 변수	기능
DB_NAME	MySQL DB 이름. Cacti, Spine Poller 공유
DB_USER	MySQL DB 사용자. Cacti, Spine Poller 공유
DB_PASS	MySQL DB 비밀번호. Cacti, Spine Poller 공유
DB_HOST	MySQL DB IP/FQDN/호스트/컨테이너이름
DB_PORT	MySQL DB 포트. 기본값 3306
CACTI_URL_PATH	기본값은 cacti. ex) http:///cacti. 루트 URL 변경만 허용되므로 “cacti” 만 변경 가능. “ccc/bb” 같은 것 불가능
DB_ROOT_PASS	`INITIALIZE_DB`가 1로 설정된 경우 필요
INITIALIZE_DB	`0: false` / `true: 1`. true면 컨테이너는 대상 데이터베이스에 대한 `DB_ROOT_PASS`를 요구. DB 초기화 설정
TZ	타임존 설정
BACKUP_RETENTION	보관할 백업 파일의 수
REMOTE_POLLER	`0: false` / `true: 1`
RDB_NAME	Cacti Master MySQL DB 이름. Cacti, Spine Poller 공유
RDB_USER	Cacti Master MySQL DB 사용자
RDB_PASS	Cacti Master MySQL DB 사용자의 비밀번호
RDB_HOST	Cacti Master MySQL DB가 사용하는 IP/FQDN/호스트/컨테이너이름
RDB_PORT	Cacti Master MySQL DB 사용 포트

DB 파라미터

MySQL 변수	추천 값	설명
Version	>= 5.6	MySQL 5.6+ 및 MariaDB 10.0+은 훌륭한 릴리스 버전으로, 안정성과 성능이 뛰어납니다. 특히 최신 릴리스는 네트워킹 문제를 해결하여 Spine의 신뢰성을 개선합니다.
collation_server	utf8mb4_unicode_ci	영어 이외의 언어를 사용할 경우, 일부 문자가 1바이트 이상을 차지하므로 `utf8mb4_unicode_ci` 정렬 타입을 사용하는 것이 중요합니다.
character_set_client	utf8mb4	영어 이외의 언어를 사용할 경우, 일부 문자가 1바이트 이상을 차지하므로 `utf8mb4` 문자셋을 사용하는 것이 중요합니다.
max_connections	>= 100	Spine 데이터 수집기와 로그인 수에 따라 많은 MySQL 연결이 필요할 수 있습니다. Spine의 연결 수 계산법은 다음과 같습니다: `total_connections = total_processes * (total_threads + script_servers + 1)`. 사용자 연결을 위한 여유 공간을 남겨야 합니다.
max_heap_table_size	>= 10% RAM	Cacti 성능 향상 기능을 사용하여 메모리 스토리지 엔진을 선택할 경우, 시스템 메모리 테이블 공간이 부족하기 전에 Performance Booster 버퍼를 플러시해야 합니다. 이 값은 시스템 메모리의 10%로 설정하는 것이 권장되지만, SSD 디스크를 사용하거나 작은 시스템에서는 무시할 수도 있습니다.
max_allowed_packet	>= 16777216	원격 폴링 기능을 사용할 때, 많은 데이터가 메인 서버에서 원격 폴러로 동기화됩니다. 따라서 이 값을 16M 이상으로 설정해야 합니다.
tmp_table_size	>= 64M	서브쿼리를 실행할 때, 임시 테이블 크기를 크게 설정하면 메모리 내에 임시 테이블을 유지할 수 있습니다.
join_buffer_size	>= 64M	조인 연산이 이 크기보다 작으면 메모리에 저장되어 임시 파일로 쓰여지지 않습니다.
innodb_file_per_table	ON	InnoDB 스토리지를 사용할 때, 테이블 공간을 분리하여 관리가 더 간편해집니다. 현재 OFF로 설정되어 있다면 이 기능을 활성화하고 InnoDB 테이블에 대해 `ALTER` 명령을 실행하여 마이그레이션할 수 있습니다.
innodb_file_format	Barracuda	`innodb_file_per_table`을 사용할 때, 파일 형식을 Barracuda로 설정해야 합니다. 이는 특정 Cacti 테이블에 필요한 긴 인덱스를 허용합니다.
innodb_large_prefix	1	테이블에 매우 큰 인덱스가 있는 경우, Barracuda 파일 형식과 함께 이 값을 1로 설정해야 합니다. 그렇지 않으면 일부 플러그인이 테이블을 제대로 생성하지 못할 수 있습니다.
innodb_buffer_pool_size	>= 25% RAM	InnoDB는 가능한 한 많은 테이블과 인덱스를 시스템 메모리에 보관합니다. 이 값을 충분히 크게 설정하여 테이블과 인덱스를 메모리에 저장하세요. `/var/lib/mysql/cacti` 디렉토리의 크기를 확인하면 적절한 값을 설정하는 데 도움이 됩니다.
innodb_doublewrite	ON	ZFS 또는 FusionI/O와 같은 내부 저널링 기능을 가진 파일 시스템을 사용하는 경우가 아니라면 이 값을 ON으로 유지하세요. 하지만 시스템 안정성이 매우 높고 백업이 잘 되어 있다면 OFF로 설정하여 데이터베이스 성능을 약 50% 개선할 수 있습니다.
innodb_lock_wait_timeout	>= 50	비정상적인 쿼리로 인해 데이터베이스가 다른 사용자에게 응답하지 못하는 것을 방지합니다.
innodb_flush_log_at_timeout	>= 3	높은 I/O 시스템에서 이 값을 1초 이상으로 설정하면 디스크 I/O가 더 순차적으로 작동할 수 있습니다.
innodb_read_io_threads	>= 32	최신 SSD 스토리지에서는 높은 I/O 특성을 가진 애플리케이션에 다중 읽기 I/O 스레드가 유리합니다.
innodb_write_io_threads	>= 16	최신 SSD 스토리지에서는 높은 I/O 특성을 가진 애플리케이션에 다중 쓰기 I/O 스레드가 유리합니다.
innodb_buffer_pool_instances	>= 9	InnoDB는 `innodb_buffer_pool`을 메모리 영역으로 분리하여 성능을 향상합니다. 1GB 이하에서는 `pool size / 128MB`를 사용하고, 최대값은 64로 설정합니다.
innodb_io_capacity	5000	SSD 디스크에서는 5000을 사용하고, 물리적 디스크에서는 활성 드라이브 수에 200을 곱한 값을 사용합니다. NVMe 또는 PCIe 플래시의 경우 최대 100,000까지 설정 가능합니다.
innodb_io_capacity_max	10000	SSD 디스크에서는 10,000을 사용하고, 물리적 디스크에서는 활성 드라이브 수에 2000을 곱한 값을 사용합니다. NVMe 또는 PCIe 플래시의 경우 최대 200,000까지 설정 가능합니다.
memory_limit	>= 800M	메모리 제한은 최소 800MB로 설정하세요.
max_execution_time	>= 60	PHP 스크립트 실행 시간을 최소 60초로 설정하세요.

Cacti Conainer 구조

Sun, 27 Jul 2025 09:00:00 +0900

https://github.com/scline/docker-cacti

Dockerfile

https://github.com/scline/docker-cacti/blob/master/Dockerfile
Rocky 9.0을 베이스 이미지로 사용
환경 변수로 DB 접속 정보, URL 경로, PHP 기본값 설정
start.sh 복사 및 실행
cacti + spine tar.gz 복사
서포트 파일(configs, configs/crontab, backup, upgrade, restore) 복사
RUN
- sh 파일 실행 권한 추가
- 볼륨 디렉토리 /backups, /cacti, /spine 생성
- 패키지 업데이트 및 설치(php, mariadb, 소스 설치 도구 등)

start.sh

https://github.com/scline/docker-cacti/blob/master/start.sh
초기 환경 설정
- PHP 설정, 시스템 TZ 설정
새 설치 여부 판단
- /cacti/install.lock 파일의 존재 여부로 이미 설치된 상태인지 판단
- Cacti와 Spine 파일 압축 해제, 필요한 디렉토리로 이동
- 템플릿 파일, 플러그인, 설정 파일들을 적절한 위치에 복사하여 기본 환경을 구성
- DB가 준비될 때까지 대기 후, 데이터베이스 생성 및 사용자 권한 설정, 그리고 cacti.sql 파일을 DB에 적용하여 초기 데이터를 세팅합니다.
- REMOTE_POLLER가 1이면, 마스터와의 설정 연동을 위한 추가 작업(예, config.php 수정, 파일 권한 조정 등)을 수행합니다.
서비스 시작
- crond, snmpd, php-fpm, apache 실행

Compose 구조

https://github.com/scline/docker-cacti/blob/master/docker-compose/cacti_multi_shared.yml
Cacti Master+ Cacti Master DB + Poller + Poller DB

Cacti
- 위 Dockerfile로 생성한 cacti 이미지 사용
- 웹 인터페이스 및 기본 Cacti 기능용 주 컨테이너
- 환경변수로 db 접속 정보 설정
- /cacti, /spine, /backups 볼륨 공유
Poller
- 위 Dockerfile로 생성한 cacti 이미지 사용
- 환경변수 REMOTE_POLLER=1가 설정되어 원격 풀러(데이터 수집 전용)로 동작
- cacti_poller DB 접속 정보와 동시에 마스터 DB 접속 정보를 전달받아, 마스터로부터 설정을 가져와서 폴링 작업만 수행하도록 구성
- /cacti, /spine, /backups 볼륨 공유
DB
- MariaDB 10.3 이미지 사용하며, Cacti와 Poller가 각각 DB 사용
Network
- 4개 컨테이너가 같은 네트워크공유
Volume
- Cacti와 Poller가 호스트의 /cacti, /spine, /backups 볼륨 공유
- /var/lib/mysql를 db volume으로 사용