ITAM/docs/itam_cicd_setup.md

ITAM CI/CD 설정 가이드

1. 문서 목적

이 문서는 현재 ITAM 저장소에 구성된 CI/CD 파일을 실제 운영에 연결하기 위해 필요한 기준을 정리한 가이드다.

대상 범위는 아래와 같다.

1. Gitea Actions workflow 역할
2. Gitea Variables / Secrets 설정값
3. 운영 서버 배포 디렉토리 기준
4. 운영 영속 경로 기준
5. production deploy 실행 전 확인 사항

---

2. 현재 CI/CD 구성

현재 .gitea/workflows에는 ITAM 관련 workflow만 남겨둔 상태다.

1. itam_code_check.yml
2. itam_docker_build_check.yml
3. itam_production_deploy.yml

각 workflow의 역할은 아래와 같다.

1. itam_code_check.yml: TypeScript/Vite build와 compose 문법 검증
2. itam_docker_build_check.yml: 운영용 Docker 이미지 빌드 가능 여부 검증
3. itam_production_deploy.yml: 운영 서버에 SSH 접속 후 실제 배포 수행

현재 배포 흐름은 아래와 같다.

flowchart LR
  DEV["Developer Push or Manual Run"] --> CODE["ITAM Code Check"]
  CODE --> BUILD["ITAM Docker Build Check"]
  BUILD --> DEPLOY["ITAM Production Deploy"]
  DEPLOY --> HOST["Production Host"]
  HOST --> APP["docker compose up -d --build"]
  linkStyle default stroke:#d32f2f,stroke-width:2px;

---

3. Gitea Variables / Secrets 기준

itam_production_deploy.yml이 정상 동작하려면 아래 값이 필요하다.

3.1 Variables

아래 항목은 Gitea repository Variables에 등록한다.

Key	설명	예시
PROD_HOST	운영 서버 SSH 접속 호스트	10.0.0.25
PROD_USER	운영 서버 SSH 사용자	deploy
PROD_DEPLOY_PATH	서버에서 저장소를 배포할 경로	/opt/itam
PROD_BACKUP_ROOT	배포 전 백업 저장 경로, 배포 경로 바깥이어야 함	/opt/itam-backups
PROD_GIT_URL	운영 서버에서 pull 가능한 저장소 주소	git@gitea.example.com:team/itam.git
PROD_DB_HOST	외부 MySQL 호스트	172.16.8.151
PROD_DB_PORT	외부 MySQL 포트	3306
PROD_DB_USER	운영 DB 계정	itam_admin
PROD_DB_NAME	운영 DB 이름	itam
PROD_LOG_LEVEL	애플리케이션 로그 레벨	info

3.2 Secrets

아래 항목은 Gitea repository Secrets에 등록한다.

Key	설명
PROD_SSH_PRIVATE_KEY	운영 서버 접속용 개인키
PROD_DB_PASS	운영 DB 비밀번호

3.3 운영 원칙

1. PROD_DB_PASS는 Variables가 아니라 Secrets에만 둔다.
2. PROD_SSH_PRIVATE_KEY는 배포 전용 계정 키를 사용한다.
3. PROD_GIT_URL은 운영 서버에서 직접 pull 가능한 주소여야 한다.
4. 운영 서버의 known_hosts는 workflow에서 자동 등록되지만, 최초 운영 전 수동 접속 검증도 함께 수행하는 것이 안전하다.
5. PROD_BACKUP_ROOT는 PROD_DEPLOY_PATH 내부가 아니라 바깥 경로를 사용해야 한다.

---

4. 운영 서버 배포 디렉토리 기준

현재 itam_production_deploy.yml은 운영 서버에서 아래 흐름으로 배포를 수행한다.

1. PROD_DEPLOY_PATH 디렉토리를 생성한다.
2. 기존 운영 상태가 있으면 배포 전 백업을 수행한다.
3. 해당 경로에 저장소를 clone 또는 fetch 한다.
4. 지정 브랜치로 checkout 한다.
5. uploads, logs/nginx 디렉토리를 생성한다.
6. .env.deploy를 서버의 .env로 복사한다.
7. docker compose -f docker-compose.prod.yaml up -d --build를 실행한다.

권장 디렉토리 구조는 아래와 같다.

/opt/itam/
  .env
  docker-compose.prod.yaml
  Dockerfile.frontend.prod
  Dockerfile.backend.prod
  map_config.json
  uploads/
  logs/
    nginx/
  docker/
    nginx/
      default.conf
    frontend/
      default.conf
  src/
  public/
  img/

/opt/itam-backups/
  db/
  files/

현재 구조 기준 배포 관계는 아래와 같다.

flowchart TB
  subgraph HOST["Production Host"]
    REPO["PROD_DEPLOY_PATH"]
    ENV[".env"]
    UP["uploads/"]
    LOGS["logs/nginx/"]
    MAP["map_config.json"]
  end

  subgraph CTR["Docker Services"]
    NGINX["itam-nginx"]
    FRONT["itam-frontend"]
    BACK["itam-backend"]
  end

  DB["External MySQL"]

  REPO --> NGINX
  ENV --> BACK
  UP --> BACK
  MAP --> BACK
  LOGS --> NGINX
  REPO --> BAK["PROD_BACKUP_ROOT"]
  NGINX --> FRONT
  NGINX --> BACK
  BACK --> DB
  linkStyle default stroke:#d32f2f,stroke-width:2px;

---

5. 영속 경로 기준

현재 docker-compose.prod.yaml 기준으로 운영에서 유지되어야 하는 경로는 아래와 같다.

1. .env
2. uploads/
3. map_config.json
4. logs/nginx/
5. PROD_BACKUP_ROOT

각 경로의 의미는 아래와 같다.

1. .env: backend 런타임 환경변수
2. uploads/: 업로드 파일 데이터
3. map_config.json: 위치/맵 구성 데이터
4. logs/nginx/: reverse proxy 접근 로그 및 에러 로그
5. PROD_BACKUP_ROOT: 배포 전 DB dump와 운영 파일 아카이브 저장 위치

운영 기준으로 보면 uploads/와 map_config.json은 애플리케이션 데이터이고, .env는 환경 설정이며, logs/nginx/는 운영 추적 데이터다.

즉 서버 운영 시 컨테이너만 다시 띄우면 되는 구조가 아니라, 이 경로들이 유지되는 것을 전제로 배포가 성립한다.

---

6. 배포 전 체크리스트

itam_production_deploy.yml 실행 전 아래 항목을 먼저 확인한다.

1. 운영 서버에 Docker Engine과 docker compose가 설치되어 있어야 한다.
2. 운영 서버의 배포 계정이 Docker 실행 권한을 가져야 한다.
3. 운영 서버에서 PROD_GIT_URL로 직접 git fetch가 가능해야 한다.
4. 외부 MySQL 접속 정보가 실제 운영망 기준으로 열려 있어야 한다.
5. 운영 서버에 map_config.json 초기 파일이 존재해야 한다.
6. 방화벽 또는 보안 장비에서 80 포트 접근 정책이 정리되어 있어야 한다.

권장 확인 명령 예시는 아래와 같다.

docker --version
docker compose version
git ls-remote <PROD_GIT_URL>
test -f map_config.json
test -d uploads

---

7. 현재 구조에서의 해석

현재 ITAM CI/CD는 staging 없이도 운영 배포가 가능한 최소 구조로 정리되어 있다.

이 구조의 장점은 아래와 같다.

1. workflow 수가 적어서 관리가 단순하다.
2. 운영 배포에 필요한 변수와 시크릿 범위가 명확하다.
3. staging이 필요해지면 production deploy workflow를 복제해 별도 환경으로 확장하기 쉽다.

즉, 지금 단계에서는 production 기준을 먼저 고정하고, staging은 동일 패턴으로 추후 추가하는 전략이 적절하다.

---

8. 다음 권장 작업

현재 문서 기준으로 바로 이어서 할 작업은 아래 순서가 적절하다.

1. PROD_DEPLOY_PATH 실제 서버 경로 확정
2. 운영 서버 배포 계정 생성 및 SSH 키 등록
3. map_config.json, uploads/ 초기 데이터 준비
4. production deploy workflow에 smoke check 추가
5. 로그 로테이션과 백업/복구 절차 문서화