MVPTeam/test
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: cicd pipeline

Browse Source
This commit is contained in:
dean[백병남]
2025-11-12 23:02:47 +09:00
parent 1fb168850b
commit f1cd9b7fdb
11 changed files with 821 additions and 99 deletions
Download Patch File Download Diff File Expand all files Collapse all files

393
README.md Normal file
View File

@@ -0,0 +1,393 @@
# KAMCO Change Detection API
> KAMCO 변화 탐지 시스템을 위한 백엔드 API 서버
## 📋 프로젝트 소개
**kamco-change-detection-api**는 공간 데이터의 변화를 탐지하고 관리하기 위한 RESTful API 서버입니다.
JTS(Java Topology Suite)를 활용한 지오메트리 데이터 처리와 PostgreSQL을 통한 공간 데이터 저장을 지원합니다.
## 🛠️ 기술 스택
| Category | Technology |
|----------|------------|
| **Language** | Java 21 |
| **Framework** | Spring Boot 3.5.7 |
| **Database** | PostgreSQL (with PostGIS) |
| **ORM** | Spring Data JPA + Hibernate |
| **Query** | QueryDSL 5.0.0 (Jakarta) |
| **Geospatial** | JTS (Java Topology Suite) + GeoJSON |
| **Connection Pool** | HikariCP |
| **Build Tool** | Gradle 8.x |
| **Monitoring** | Spring Boot Actuator |
| **Container** | Docker + Docker Compose |
| **CI/CD** | Jenkins |
## 🚀 시작하기
### 필수 요구사항
- Java 21 (JDK 21)
- PostgreSQL 12+ (PostGIS 확장 필요)
- Gradle 8.x (또는 Gradle Wrapper 사용)
- Docker & Docker Compose (선택사항)
### 로컬 환경 설정
1. **저장소 클론**
```bash
git clone https://10.100.0.10:3210/dabeeo/kamco-dabeeo-backoffice.git
cd kamco-back
```
2. **데이터베이스 설정**
PostgreSQL 데이터베이스를 준비하고 `src/main/resources/application-local.yml`을 생성:
```yaml
spring:
config:
activate:
on-profile: local
datasource:
url: jdbc:postgresql://localhost:5432/your_database
username: your_username
password: your_password
```
> **참고**: `application-local.yml`은 `.gitignore`에 포함되어 있어 Git에 커밋되지 않습니다.
3. **빌드 및 실행**
```bash
# 빌드
./gradlew build
# 실행 (local 프로파일)
./gradlew bootRun
# 또는 JAR 파일로 실행
java -jar build/libs/ROOT.jar
```
서버가 시작되면 http://localhost:8080 에서 접근 가능합니다.
## ⚙️ 프로파일 설정
애플리케이션은 환경별로 다른 설정을 사용합니다:
| 프로파일 | 환경 | 포트 | 설정 파일 |
|---------|------|------|-----------|
| `local` | 로컬 개발 | 8080 | `application.yml` (기본) |
| `dev` | 개발 서버 | 7100 | `application-dev.yml` |
| `prod` | 운영 서버 | 8080 | `application-prod.yml` |
### 프로파일 활성화
```bash
# 개발 환경으로 실행
./gradlew bootRun --args='--spring.profiles.active=dev'
# JAR 실행 시
java -jar build/libs/ROOT.jar --spring.profiles.active=dev
```
## 🧪 테스트
```bash
# 전체 테스트 실행
./gradlew test
# 특정 테스트 클래스 실행
./gradlew test --tests com.kamco.cd.kamcoback.KamcoBackApplicationTests
# 테스트 리포트 확인
open build/reports/tests/test/index.html
```
## 📦 빌드
```bash
# 전체 빌드 (테스트 포함)
./gradlew clean build
# 테스트 제외 빌드 (CI/CD에서 사용)
./gradlew clean build -x test
# JAR 파일만 생성
./gradlew bootJar
```
빌드된 JAR 파일: `build/libs/ROOT.jar`
## 🐳 Docker로 실행하기
### Docker Compose 사용 (권장)
```bash
# 빌드 및 실행
docker-compose -f docker-compose-dev.yml up -d
# 로그 확인
docker-compose -f docker-compose-dev.yml logs -f
# 중지
docker-compose -f docker-compose-dev.yml down
```
### Docker만 사용
```bash
# 이미지 빌드
docker build -f Dockerfile-dev -t kamco-changedetection-api:latest .
# 컨테이너 실행
docker run -d \
--name kamco-changedetection-api \
-p 7100:8080 \
kamco-changedetection-api:latest
# 로그 확인
docker logs -f kamco-changedetection-api
```
## 📡 API 및 모니터링
### Actuator 헬스체크
애플리케이션 상태를 확인할 수 있는 엔드포인트가 제공됩니다:
```bash
# 헬스체크
curl http://localhost:8080/monitor/health
# 응답 예시
{
"status": "UP",
"components": {
"db": {
"status": "UP"
},
"diskSpace": {
"status": "UP"
}
}
}
```
**Actuator 엔드포인트**:
- `/monitor/health` - 애플리케이션 헬스 체크
- `/monitor/health/readiness` - Kubernetes Readiness Probe
- `/monitor/health/liveness` - Kubernetes Liveness Probe
## 🏗️ 프로젝트 구조
```
kamco-back/
├── src/
│ ├── main/
│ │ ├── java/com/kamco/cd/kamcoback/
│ │ │ ├── KamcoBackApplication.java # 메인 애플리케이션
│ │ │ ├── config/ # 설정 클래스
│ │ │ │ ├── WebConfig.java # Jackson, CORS 설정
│ │ │ │ └── StartupLogger.java # 시작 로그
│ │ │ ├── common/ # 공통 유틸리티
│ │ │ │ └── utils/geometry/ # GeoJSON 직렬화
│ │ │ ├── domain/ # 도메인 엔티티 (예정)
│ │ │ ├── repository/ # 리포지토리 (예정)
│ │ │ ├── service/ # 비즈니스 로직 (예정)
│ │ │ └── controller/ # REST 컨트롤러 (예정)
│ │ └── resources/
│ │ ├── application.yml # 기본 설정 + local/prod
│ │ └── application-dev.yml # 개발 환경 설정
│ └── test/ # 테스트 코드
├── build.gradle # Gradle 빌드 설정
├── Dockerfile-dev # Docker 이미지 정의
├── docker-compose-dev.yml # Docker Compose 설정
├── Jenkinsfile-dev # Jenkins CI/CD 파이프라인
├── .editorconfig # 코드 스타일 설정
├── intellij-java-google-style.xml # IntelliJ 코드 스타일
└── README.md # 이 문서
```
## 🎨 코드 스타일
프로젝트는 **Google Java Style Guide**를 따르며, 일부 커스터마이징이 적용되어 있습니다:
- **들여쓰기**: 탭 (표시 너비: 2칸)
- **최대 줄 길이**: 100자
- **줄 바꿈**: LF (Unix 스타일)
- **인코딩**: UTF-8
### IntelliJ IDEA 설정
1. `Preferences` → `Editor` → `Code Style` → `Java`
2. `Import Scheme` → `intellij-java-google-style.xml` 선택
## 📐 주요 기능
### GeoJSON 지원
JTS Geometry 타입이 자동으로 GeoJSON 형식으로 직렬화/역직렬화됩니다:
```java
@Entity
public class SpatialEntity {
@Column(columnDefinition = "geometry(Point,4326)")
private Point location;
@Column(columnDefinition = "geometry(Polygon,4326)")
private Polygon boundary;
}
```
**특징**:
- 16자리 정밀도 (기본 8자리에서 증가)
- Point, Polygon, Geometry 타입 지원
- 자동 JSON 변환 (Jackson ObjectMapper 설정)
### QueryDSL 설정
타입 안전한 쿼리를 위해 QueryDSL이 설정되어 있습니다:
```java
// Q-class는 빌드 시 자동 생성됨
QSpatialEntity entity = QSpatialEntity.spatialEntity;
List<SpatialEntity> results = queryFactory
.selectFrom(entity)
.where(entity.name.eq("example"))
.fetch();
```
**Q-class 생성 위치**: `build/generated/sources/annotationProcessor/java/main`
## 🚢 배포
### Jenkins CI/CD
Jenkins를 통한 자동 배포가 설정되어 있습니다 (`Jenkinsfile-dev`):
**파이프라인 단계**:
1. **Checkout**: Git 저장소에서 코드 가져오기 (develop 브랜치)
2. **Get Commit Hash**: 버전 태깅용 커밋 해시 추출
3. **Build**: Gradle로 JAR 빌드 (테스트 제외)
4. **Docker Build & Deploy**: Docker 이미지 빌드 및 배포
5. **Cleanup**: 오래된 이미지 정리
**자동 기능**:
- Git 커밋 해시로 이미지 태깅
- 기존 컨테이너 자동 교체
- 헬스체크로 배포 검증
- 오래된 이미지 자동 정리 (최신 5개 유지)
### 수동 배포
```bash
# 1. 빌드
./gradlew clean build -x test
# 2. Docker 이미지 빌드
docker-compose -f docker-compose-dev.yml build
# 3. 배포
docker-compose -f docker-compose-dev.yml up -d
# 4. 헬스체크
curl http://localhost:7100/monitor/health
```
## 🔧 개발 가이드
### 새로운 엔티티 추가
1. `domain` 패키지에 엔티티 클래스 생성
2. JPA 어노테이션 설정
3. 빌드하여 Q-class 자동 생성
4. Repository 인터페이스 작성 (QueryDSL custom 메서드 포함)
### GeoJSON 데이터 다루기
```java
// Controller에서 GeoJSON 수신/반환
@PostMapping("/spatial")
public ResponseEntity<SpatialEntity> create(@RequestBody SpatialEntity entity) {
// Point, Polygon이 자동으로 GeoJSON에서 변환됨
return ResponseEntity.ok(spatialService.save(entity));
}
// 응답 예시
{
"id": 1,
"location": {
"type": "Point",
"coordinates": [126.9779692, 37.5662952]
}
}
```
### 데이터베이스 마이그레이션
현재 설정은 `ddl-auto: validate`이므로 스키마 변경 시:
1. 수동으로 마이그레이션 스크립트 작성
2. 또는 개발 중에는 `ddl-auto: update` 사용 (주의 필요)
3. 운영 환경에서는 반드시 `validate` 유지
## 📝 환경 변수
Docker Compose 또는 시스템 환경 변수로 설정 가능:
| 변수명 | 설명 | 기본값 |
|--------|------|--------|
| `SPRING_PROFILES_ACTIVE` | 활성 프로파일 | `local` |
| `IMAGE_TAG` | Docker 이미지 태그 | `latest` |
| `TZ` | 타임존 | `Asia/Seoul` |
## 🐛 트러블슈팅
### DataSource 설정 오류
```
Failed to configure a DataSource: 'url' attribute is not specified
```
**해결 방법**:
1. 프로파일 이름 확인: `dev`, `prod`, `local` (철자 정확히)
2. 해당 프로파일의 `application-{profile}.yml`에 datasource 설정 존재 확인
3. PostgreSQL 접속 정보 확인
### Q-class가 생성되지 않음
```bash
# 강제로 Q-class 재생성
./gradlew clean compileJava
```
생성 위치: `build/generated/sources/annotationProcessor/java/main`
### Docker 컨테이너 헬스체크 실패
```bash
# 컨테이너 로그 확인
docker logs kamco-changedetection-api
# 직접 헬스체크
docker exec kamco-changedetection-api curl http://localhost:8080/monitor/health
```
## 📚 참고 문서
- [Spring Boot 3.5.7 Documentation](https://docs.spring.io/spring-boot/3.5.7/reference/)
- [Spring Data JPA](https://docs.spring.io/spring-data/jpa/reference/)
- [QueryDSL](https://querydsl.com/static/querydsl/latest/reference/html/)
- [JTS Topology Suite](https://github.com/locationtech/jts)
- [GeoJSON Specification](https://geojson.org/)
## 📄 라이선스
Copyright © 2024 KAMCO. All rights reserved.
## 👥 기여자
- Development Team at KAMCO