arko_renual/deploy/dev/README.md

arko_renual 개발서버 배포 · CI/CD (csv.zioinfo.co.kr)

대상 환경

항목	값
서버	zio-server / 101.79.17.164 (Ubuntu 24.04.1, 2코어, 메모리 7.8G, 디스크 99G)
도메인	csv.zioinfo.co.kr → nginx(443) → Tomcat(127.0.0.1:8088)
저장소	https://git.zioinfo.co.kr/somang4819/arko_renual.git (Gitea 1.22.3)
CI/CD	Gitea Actions + act_runner (host 모드, 같은 서버에서 빌드·배포)
JDK	8 (Temurin) — source/target 1.7이라 서버 기본 JDK 17/21로는 컴파일 불가
DB	서버 MariaDB 10.11 127.0.0.1:3306 스키마 csv (이미 존재, 188테이블/실데이터)
배포 형태	ROOT 전개 필수 — JSP가 /new/css/... 처럼 컨텍스트 경로 없이 하드코딩

파일 구성

파일	설치 위치	역할
00-server-setup.sh	(1회 실행)	JDK8·Tomcat9·디렉토리·systemd·nginx·act_runner 구축
arko-dev-deploy.sh	/opt/arko-dev/bin/	WAR 검증 → 백업 → 재전개 → 설정주입 → 기동 → 헬스체크(실패 시 롤백)
arko-dev.service	/etc/systemd/system/	Tomcat 9 서비스 (힙 768m)
arko-dev-runner.service	/etc/systemd/system/	Gitea Actions runner (host 모드)
runner-config.yaml	/opt/arko-dev/runner/config.yaml	러너 설정 (동시 1개, 캐시 off)
csv.zioinfo.co.kr.conf	/etc/nginx/sites-available/	리버스 프록시
../../.gitea/workflows/deploy-dev.yml	저장소	master push → 빌드·배포

서버 디렉토리 배치

/opt/arko-dev/
├── jdk8/            Temurin 8 (빌드·런타임 공용)
├── tomcat/          Tomcat 9 — webapps/ROOT 에 전개
├── config/          globals-dev.properties, globals-live.properties  ← git에 없음, 서버에만 보관
├── bin/             arko-dev-deploy.sh
├── backup/          ROOT_<타임스탬프>.tar.gz (최근 3개 유지)
├── upload/          업로드 파일 (재배포로 사라지지 않도록 ROOT/file 에 심볼릭 링크)
├── runner/          act_runner 작업 디렉토리
└── logs/            deploy.log

구축 절차

# 1. 산출물 업로드
scp -r deploy/dev root@101.79.17.164:/tmp/arko-deploy

# 2. 서버 구축 (멱등 — 다시 실행해도 안전)
ssh root@101.79.17.164 'bash /tmp/arko-deploy/00-server-setup.sh'

# 3. 환경설정 배치 (.gitignore 대상이라 저장소에 없음 — 없으면 기동 실패)
scp src/main/resources/egovframework/egovProps/globals-{dev,live}.properties \
    root@101.79.17.164:/opt/arko-dev/config/
#    → 서버에서 DB(127.0.0.1:3306/csv)·도메인(csv.zioinfo.co.kr)·메일/SMS 값 수정

# 4. Gitea runner 등록 (토큰은 Gitea 웹에서 발급)
ssh root@101.79.17.164 'cd /opt/arko-dev/runner && \
  act_runner register --no-interactive --instance https://git.zioinfo.co.kr \
    --token <등록토큰> --name arko-dev-runner --labels arko-dev:host && \
  install -m 644 /tmp/arko-deploy/runner-config.yaml /opt/arko-dev/runner/config.yaml && \
  install -m 644 /tmp/arko-deploy/arko-dev-runner.service /etc/systemd/system/ && \
  systemctl daemon-reload && systemctl enable --now arko-dev-runner'

# 5. DNS A 레코드 등록 (사용자 작업): csv.zioinfo.co.kr → 101.79.17.164
#    등록 후 SSL 발급
ssh root@101.79.17.164 'certbot --nginx -d csv.zioinfo.co.kr'

# 6. 워크플로 push → 이후 master push마다 자동 배포
git add .gitea/workflows/deploy-dev.yml deploy/
git commit -m "개발서버 배포 및 Gitea Actions 파이프라인 추가"
git push origin master

평상시 배포 흐름

# 1) 개발자 PC에서 빌드 + WAR 업로드
bash deploy/dev/build-and-upload.sh

# 2) push → Gitea Actions(deploy-dev)가 자동 배포
git push origin master
#    진행 상황: https://git.zioinfo.co.kr/somang4819/arko_renual/actions

빌드는 개발자 PC에서만 한다. 서버(2코어/메모리 여유 1G)에서 Maven을 돌리면 다른 40여 개 서비스까지 흔들리기 때문이다.

push 없이 즉시 반영:

bash deploy/dev/build-and-upload.sh --deploy

재배포·롤백: Gitea 웹 > Actions > deploy-dev > Run workflow > deploy 또는 rollback

운영 명령

systemctl status arko-dev            # 상태
journalctl -u arko-dev -f            # 서비스 로그
tail -f /opt/arko-dev/tomcat/logs/catalina.out
tail -f /opt/arko-dev/logs/deploy.log

# 수동 롤백
systemctl stop arko-dev
rm -rf /opt/arko-dev/tomcat/webapps/ROOT
tar -xzf /opt/arko-dev/backup/ROOT_<타임스탬프>.tar.gz -C /opt/arko-dev/tomcat/webapps
systemctl start arko-dev

알려진 제약 · 주의

1. 서버 자원이 빠듯하다. 조사 시점 기준 디스크 99%(여유 1.8G), 메모리 여유 1.3G, 부하 평균 11~17, 40개 이상 서비스 동거. 구축 전 디스크 정리가 사실상 필수다(journalctl --vacuum-time=7d, /var/log 정리 등). 00-server-setup.sh는 여유 2.5GB 미만이면 스스로 중단한다.
2. WAR가 192MB다. 전개본·백업까지 하면 배포 1회에 약 600MB를 쓴다. 백업은 3개까지만 유지한다.
3. globals-dev/live.properties는 저장소에 없다(.gitignore). 서버 config/에 두고 배포 때 주입한다. context-datasource.xml이 globals-dev.properties만 읽으므로 이 파일이 없으면 기동 자체가 실패한다.
4. ROOT 배포만 가능하다. /arko 같은 서브 컨텍스트로 올리면 CSS/JS/이미지가 전부 404난다.
5. DB는 기존 csv 스키마를 그대로 쓴다. 실데이터(회원 75,301건 등)가 들어 있으므로 개인정보보호 신규 테이블(SFR-001~004) 적용 여부와 마스킹 필요성은 별도 확인이 필요하다.
6. JDK 17/21로는 빌드되지 않는다. maven-compiler-plugin이 source/target 1.7이고 JDK 9+는 1.7을 지원하지 않는다.