226 lines
7.2 KiB
Markdown
226 lines
7.2 KiB
Markdown
# 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 접속 후 실제 배포 수행
|
|
|
|
현재 배포 흐름은 아래와 같다.
|
|
|
|
```mermaid
|
|
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`를 실행한다.
|
|
|
|
권장 디렉토리 구조는 아래와 같다.
|
|
|
|
```text
|
|
/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/
|
|
```
|
|
|
|
현재 구조 기준 배포 관계는 아래와 같다.
|
|
|
|
```mermaid
|
|
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 포트 접근 정책이 정리되어 있어야 한다.
|
|
|
|
권장 확인 명령 예시는 아래와 같다.
|
|
|
|
```bash
|
|
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. 로그 로테이션과 백업/복구 절차 문서화 |