## 🛠️ Gitea & Quartz 배포 자동화 트러블슈팅 기록

### 1. 문제의 발단: Gitea 경로 변경 (`/git/` 누락)

기존에 설정된 Gitea의 접속 주소가 `/git/` 경로를 포함하고 있었으나, 서버 재설정 과정에서 이 경로가 빠지게 되었습니다. 이로 인해 연쇄적인 문제가 발생했습니다.

- **현상:** Gitea 웹훅(Webhook)이 서버의 수신기(`webhook` 서비스)에 신호를 보내지 못함.
    
- **원인:** Gitea 내부 리포지토리 설정과 외부 호출 URL이 일치하지 않아 404 에러 또는 연결 거부 발생.
    

---

### 2. 주요 장애 요인 및 해결 과정

#### 📂 [Level 1] 서비스 실행 실패 (ConditionPathExists)

- **에러:** `webhook.service was skipped because of an unmet condition check`.
    
- **원인:** 기본 설치된 `webhook` 서비스가 `/etc/webhook.conf` 파일이 있어야만 작동하도록 설정됨.
    
- **해결:** 서비스 파일(`systemd`)을 수정하여 해당 조건을 삭제하고, 우리가 직접 만든 `hooks.json`을 바라보도록 설정함.
    

#### 🔑 [Level 2] 인증 에러 (no source for value retrieval)

- **에러:** `500 | error evaluating hook: no source for value retrieval`.
    
- **원인:** `hooks.json`에는 비밀번호(Secret) 검사 로직이 있는데, Gitea 웹훅 설정에는 비밀번호가 비어 있거나 헤더 이름이 일치하지 않음.
    
- **해결:** 보안을 위해 Gitea와 서버 양쪽에 동일한 비밀번호를 설정하거나, 테스트를 위해 `trigger-rule`을 삭제하여 문턱을 낮춤.
    

#### 🚀 [Level 3] 스크립트 실행 환경 문제 (npx & node)

- **에러:** `npx: command not found` 또는 `node: No such file or directory`.
    
- **원인:** `systemd` 서비스는 사용자 터미널 환경변수(`PATH`)를 읽지 못해 NVM에 설치된 Node.js를 찾지 못함.
    
- **해결:** `deploy.sh` 상단에 Node.js 실행 파일이 있는 **절대 경로**를 `export PATH`로 직접 주입함.
    

#### 📉 [Level 4] 자원 부족 및 서버 경직 (kswapd0)

- **현상:** 빌드 시작 시 서버가 급격히 느려지며 접속이 끊김.
    
- **원인:** Quartz 빌드는 CPU와 메모리를 많이 사용하는데, 512MB~1GB 수준의 낮은 메모리로 인해 스왑(Swap) 현상이 심화됨.
    
- **해결:** 1. **Swap 확장:** 기존 스왑 파일을 **2GB**로 대폭 확장하여 물리 메모리 부족에 대비함.
    
    2. **우선순위 조정:** 빌드 명령어 앞에 **`nice -n 19`**를 붙여 다른 서비스(Nginx, Gitea)에 영향을 주지 않도록 최적화함.
    

---

### 3. 최종 자동화 아키텍처 (The "Tight" Setup)

|**구성 요소**|**역할**|**최적화 포인트**|
|---|---|---|
|**Gitea**|소스 관리 및 트리거|`/git/` 경로를 제외한 클린 URL 적용|
|**Webhook**|신호 수신기 (Port 29292)|전용 서비스 등록 및 자동 시작 설정|
|**deploy.sh**|배포 스크립트|**절대 경로 사용**, **로그 파일 기록**, **우선순위 최저 설정**|
|**Swap File**|가상 메모리 (2GB)|`/etc/fstab` 등록을 통한 영구 적용|

---

### 📝 교훈

> **경로(Path)와 환경(Environment)은 언제나 명시적이어야 한다.** > 공짜 서버일수록 수동으로 자원을 배분하고 우선순위를 관리하는 **빡빡한 최적화**가 시스템의 생명줄이 된다.