CI/CD

Kosmos 기반 프로젝트는 Gradle 멀티모듈 + GitHub Actions + Cafe24 VPS를 이용해 완전 자동화된 빌드 및 배포 파이프라인을 제공합니다. 이 문서에서는 개발자가 코드 변경 후 “push 한 번으로 서버 반영”까지 이르는 전 과정을 다룹니다.

핵심 개념: “한 명의 개발자도 안정적 배포 자동화를 갖춘다.”

1. 개요

UNeedSoft의 kosmos 프로젝트는 다음과 같은 CI/CD 전략을 사용합니다:

  • Gradle 8.5 멀티모듈 빌드 — kosmos-dsl, kosmos-spring, uneedsoft-server-100
  • Maven Local Publish — 공통 DSL 라이브러리를 로컬 Maven으로 배포
  • GitHub Actions — push 시 자동 빌드, 테스트, JAR 생성
  • Cafe24 VPS 배포 — SSH 자동 업로드 및 서비스 재시작
결과: main 브랜치에 push 하면 uneedsoft-server-100.jar가 자동 배포됩니다.

2. 프로젝트 구조

root
├── build.gradle
├── settings.gradle
├── kosmos-dsl/
│   └── src/main/java/net/uneedsoft/kosmos/dsl/...
├── kosmos-spring/
│   └── src/main/java/net/uneedsoft/kosmos/spring/...
└── uneedsoft-server-100/
    ├── src/main/java/net/uneedsoft/web/...
    └── build.gradle

각 모듈은 독립적으로 빌드 가능하지만, 상위 settings.gradle에서 버전 관리 및 종속성을 통합합니다.

3. Gradle 설정

// settings.gradle
rootProject.name = "uneedsoft"
include("kosmos-dsl", "kosmos-spring", "uneedsoft-server-100")
// build.gradle (root)
plugins {
    id "java-library"
    id "maven-publish"
}

subprojects {
    apply plugin: "java-library"
    java { toolchain { languageVersion = JavaLanguageVersion.of(17) } }

    repositories {
        mavenLocal()
        mavenCentral()
    }
}
Tip: DSL 수정 시 gradlew publishToMavenLocal을 먼저 실행해야 server 모듈이 최신 DSL을 참조합니다.

4. GitHub Actions

자동화 파이프라인은 .github/workflows/deploy.yml로 구성합니다.

name: Build & Deploy

on:
  push:
    branches: [ "main" ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup JDK 17
        uses: actions/setup-java@v4
        with:
          distribution: "temurin"
          java-version: 17

      - name: Build with Gradle
        run: ./gradlew clean build -x test

      - name: Upload artifact
        uses: actions/upload-artifact@v3
        with:
          name: server-jar
          path: uneedsoft-server-100/build/libs/*.jar

  deploy:
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Download artifact
        uses: actions/download-artifact@v3
        with:
          name: server-jar
          path: .

      - name: Deploy via SSH
        uses: appleboy/scp-action@master
        with:
          host: ${{ secrets.VPS_HOST }}
          username: ${{ secrets.VPS_USER }}
          key: ${{ secrets.VPS_KEY }}
          source: "uneedsoft-server-100-*.jar"
          target: "/home/ubuntu/deploy"
주의: VPS 접속 정보는 GitHub Secrets에 등록해야 합니다. (VPS_HOST, VPS_USER, VPS_KEY)

5. Cafe24 VPS 배포

GitHub Actions가 업로드한 uneedsoft-server-100.jar 파일은 Cafe24 VPS의 /home/ubuntu/deploy 경로에 위치하게 됩니다.

# deploy.sh
#!/bin/bash
JAR_NAME=$(ls /home/ubuntu/deploy/uneedsoft-server-100-*.jar | tail -n 1)
echo "Deploying $JAR_NAME ..."
sudo systemctl stop uneedsoft
nohup java -jar $JAR_NAME --spring.profiles.active=prod > /home/ubuntu/logs/app.log 2>&1 &
sudo systemctl start uneedsoft
echo "Deployment completed!"

이 스크립트는 VPS 내에서 서비스 프로세스를 중단 → 교체 → 재시작합니다. Systemd를 사용하는 환경이라면 다음처럼 설정 가능합니다:

# /etc/systemd/system/uneedsoft.service
[Unit]
Description=UNeedSoft Web Service
After=network.target

[Service]
ExecStart=/usr/bin/java -jar /home/ubuntu/deploy/uneedsoft-server-100.jar
Restart=always
User=ubuntu

[Install]
WantedBy=multi-user.target

6. Docker 배포 (선택)

VPS 환경 외에도 Docker 기반 배포를 지원합니다.

# Dockerfile
FROM eclipse-temurin:17-jdk-alpine
WORKDIR /app
COPY uneedsoft-server-100.jar app.jar
ENTRYPOINT ["java","-jar","app.jar"]
# 빌드 및 실행
docker build -t uneedsoft-server .
docker run -d -p 8080:8080 uneedsoft-server

7. 실행 흐름 요약

1. 개발자가 main 브랜치에 push
2. GitHub Actions 빌드 및 테스트 실행
3. 서버 JAR 생성 및 아티팩트 업로드
4. Cafe24 VPS로 SSH 업로드
5. deploy.sh 실행 → 기존 프로세스 종료 후 교체
6. 새 버전 서비스 자동 재시작

8. 모듈별 빌드 의존성

모듈 의존성 설명
kosmos-dsl 없음 HTML DSL Core
kosmos-spring kosmos-dsl Spring Boot 통합
uneedsoft-server-100 kosmos-spring 전체 웹 애플리케이션

9. 문제 해결

  • 빌드 실패 시: Gradle 캐시(~/.gradle/caches) 삭제 후 재빌드
  • 배포 실패 시: VPS_KEY 권한 확인 (chmod 600)
  • 서비스 재시작 불가: systemctl daemon-reload 후 재등록

다음으로