Tools

Coolify 기반 Spring Boot 애플리케이션 CI/CD 파이프라인 구성과 배포 자동화

jin@catsriding.com
Apr 5, 2025
Published byJin
Coolify 기반 Spring Boot 애플리케이션 CI/CD 파이프라인 구성과 배포 자동화

Step-by-Step Guide to Deploying a Spring Boot Application with Coolify on a Self-Hosted Server

Spring Boot 애플리케이션을 수정할 때마다 서버에 접속해 수동으로 빌드하고 배포하는 작업은 의외로 많은 시간과 실수를 초래합니다. 단순한 변경에도 반복적인 과정을 거쳐야 하며, 점점 관리 비용이 커지기 마련입니다.

Coolify를 활용하면 Git 기반의 자동 배포뿐만 아니라, 도메인 연결, HTTPS 인증서 발급, 서버 상태 모니터링까지 한 번에 구성할 수 있습니다. 별도의 복잡한 인프라 없이도 가능한 구조이기 때문에, 소규모 서비스나 개인 프로젝트에 특히 적합한 선택지입니다.

이 글에서는 Vultr 가상 서버 위에 Coolify를 설치하고, Docker Compose 환경에서 Spring Boot 애플리케이션을 자동 배포하는 CI/CD 파이프라인을 구축하는 과정을 단계별로 살펴봅니다.

1. 배포 자동화를 위한 Coolify 소개

개인 프로젝트나 소규모 서비스 운영에서 가장 번거로운 작업 중 하나는 배포입니다. 로컬에서 코드를 수정하고 테스트한 다음, SSH로 서버에 접속해 소스 코드를 내려받아, 필요하다면 다시 빌드하고, 컨테이너를 재시작하는 반복적인 과정을 매번 수행해야 합니다. 이러한 수동 배포 방식은 시간이 오래 걸릴 뿐만 아니라, 실수 가능성도 높습니다. 특히 여러 번 배포를 반복하거나, 여러 개의 프로젝트를 동시에 운영할 경우 이러한 작업은 점점 더 부담으로 다가옵니다.

automating-spring-boot-application-deployment-with-ci-cd-using-coolify_coolify.png

Coolify는 이러한 문제를 해결해주는 경량화된 PaaS(Platform as a Service) 솔루션입니다. 자체 서버에 설치하여 사용하는 방식으로, Heroku나 Render와 유사한 기능을 제공합니다. Git 저장소와 연동하면, Push 이벤트를 트리거로 자동으로 애플리케이션을 빌드하고 배포해줍니다. 게다가 별도의 복잡한 설정 없이도 커스텀 도메인 연결, HTTPS 인증서 발급(Let’s Encrypt), 리소스 사용량 모니터링까지 하나의 대시보드에서 손쉽게 처리할 수 있습니다.

물론 Kubernetes 기반의 ArgoCD, GitOps 방식의 CI/CD 도구들도 많이 있지만, 개인 프로젝트나 소규모 서비스에 적용하기에는 과한 면이 있습니다. 반면 Coolify는 Docker Compose 기반으로 작동하며, 간편하게 셋업할 수 있고 UI도 직관적이어서 DevOps에 익숙하지 않은 개발자에게도 진입장벽이 낮습니다.

2. Coolify 설치하기

Coolify는 다양한 환경에 설치할 수 있지만, 이 글에서는 Vultr 클라우드 컴퓨팅 플랫폼을 활용하여 설치를 진행합니다. Vultr는 AWS에 비해 상대적으로 저렴한 가격에 안정적인 컴퓨팅 자원을 제공하며, UI가 직관적이라 처음 설정하는 경우에도 진입장벽이 낮은 편입니다.

Coolify는 AWS Marketplace를 통해 AMI 이미지로도 제공되므로, AWS를 선호한다면 동일한 설치 과정을 EC2 기반으로도 쉽게 따라할 수 있습니다. 설치 방식은 유사하므로, 사용하는 인프라 환경에 맞게 선택하시면 됩니다.

automating-spring-boot-application-deployment-with-ci-cd-using-coolify_vultr.png

2-1. Vultr 서버 인스턴스 생성하기

Vultr에 가입한 후, 대시보드에서 Deploy + 버튼을 클릭하면 인스턴스 생성 화면으로 진입합니다.

이 글에서는 테스트 용도로 가장 기본적인 사양인 Shared CPU, 1 vCPU / 1 GB 메모리 모델을 선택하였습니다. Coolify 자체는 가벼운 애플리케이션이기 때문에, 소규모 프로젝트에는 이 정도의 사양으로도 충분히 동작할 것입니다. 단, 실제 운영 서비스에서 여러 컨테이너를 동시에 띄울 예정이라면 최소 4GB 이상의 메모리를 확보하는 것이 좋습니다.

automating-spring-boot-application-deployment-with-ci-cd-using-coolify_00.png

2-2. Marketplace에서 Coolify 선택 및 설치

이제 Software & Deploy Instance 섹션에서 Marketplace Apps 탭으로 이동합니다. 여기에서 Coolify를 검색하면, 미리 구성된 Coolify 이미지가 나타납니다. 해당 항목을 선택한 뒤, 하단의 Deploy Now 버튼을 클릭하면 서버 생성과 동시에 설치가 시작됩니다.

automating-spring-boot-application-deployment-with-ci-cd-using-coolify_01.png

이렇게 설치 과정은 매우 단순합니다. 별도의 Docker 설치나 명령어 입력 없이, 선택과 클릭만으로 인스턴스가 자동 초기화되고 Coolify가 함께 설치됩니다. 인스턴스 생성이 완료되면, Vultr 대시보드에서 할당된 퍼블릭 IP 주소를 확인한 후, 해당 주소로 접속하면 Coolify 초기 화면에 접근할 수 있습니다.

3. Coolify 초기 환경 설정하기

Coolify가 설치된 인스턴스는 자동으로 서버 초기화와 패키지 설치 작업을 진행합니다. 인스턴스 모델 사양에 따라 이 초기 구성 속도는 다소 차이가 있을 수 있으며, 실제 테스트에서는 약 5~10분 정도 소요되었습니다.

3-1. Coolify 대시보드 접속하기

설치가 완료되면, 해당 인스턴스의 퍼블릭 IP 주소 뒤에 포트 번호 :8000을 붙여 접속하면 Coolify의 웹 기반 GUI에 접근할 수 있습니다.

automating-spring-boot-application-deployment-with-ci-cd-using-coolify_02.png

Coolify에 처음 접속하면, 가장 먼저 관리자 계정 생성 화면이 나타납니다. 이메일 주소와 비밀번호를 입력하고 계정을 생성하면, 이후 모든 관리 작업은 이 계정을 통해 수행하게 됩니다.

automating-spring-boot-application-deployment-with-ci-cd-using-coolify_03.png

3-2. 온보딩 프로세스 완료하기

계정을 생성하면 온보딩 프로세스가 자동으로 시작됩니다. 이 과정에서는 사용자가 별도로 설정할 항목은 거의 없으며, 몇 번의 클릭만으로 기본 설정이 완료됩니다. Coolify는 사용자가 빠르게 실질적인 배포 환경 구성에 집중할 수 있도록 UI 흐름이 잘 정돈되어 있습니다.

automating-spring-boot-application-deployment-with-ci-cd-using-coolify_04.png

온보딩이 끝나면 자동으로 프로젝트 구성 페이지로 이동하게 됩니다. 이제 GitHub 저장소와 연동하여 CI/CD 파이프라인을 구성하기 위한 사전 작업으로, GitHub App 연동 단계를 진행합니다. Coolify는 GitHub App 기반의 권한 관리를 사용하므로, 저장소를 안전하게 연동하면서도 다양한 자동화 기능을 활용할 수 있습니다.

3-3. GitHub App을 통한 GitHub 연동하기

먼저, 프로젝트 생성 화면에서 Private Repository (with GitHub App) 버튼을 클릭합니다.

automating-spring-boot-application-deployment-with-ci-cd-using-coolify_05.png

이어서 상단의 + Add GitHub App 버튼을 선택하면 새로운 GitHub App 생성 모달 창이 나타납니다.

automating-spring-boot-application-deployment-with-ci-cd-using-coolify_06.png

GitHub App은 GitHub 전역에서 고유한 이름을 가져야 합니다. 이때 사용 중인 GitHub 계정명 또는 조직명을 기반으로 입력하면 충돌 가능성을 줄일 수 있습니다. 이름을 지정하고 저장소 권한을 설정한 후, 다음 단계로 이동합니다.

automating-spring-boot-application-deployment-with-ci-cd-using-coolify_07.png

이후 화면에서는 GitHub로 리디렉션되어 App 생성과 권한 위임 단계를 마무리하게 됩니다. Coolify는 필요한 권한만 요청하며, 사용자 입장에서도 신뢰할 수 있는 연동 흐름을 제공합니다. 테스트 편의상 이 글에서는 모든 리포지토리에 대한 접근 권한을 부여하였지만, 실제 운영 환경에서는 특정 리포지토리만 선택적으로 연동하는 것이 보다 안전한 접근 방식입니다.

automating-spring-boot-application-deployment-with-ci-cd-using-coolify_08.png

3-4. GitHub 저장소 연동 상태 확인하기

GitHub App 연동이 완료되면, Coolify 내에서 접근 가능한 리포지토리 목록이 자동으로 표시됩니다.

automating-spring-boot-application-deployment-with-ci-cd-using-coolify_09-1.png

이제 애플리케이션 소스 코드와 Docker 배포 구성을 정리하고, 실제 배포 대상 프로젝트를 준비합니다.

4. Spring Boot 애플리케이션과 Docker 배포 구성 준비

이제 실제로 배포할 애플리케이션 코드를 준비합니다. 여기서는 가장 단순한 형태의 Spring Boot 프로젝트를 사용하여 테스트를 진행합니다. 단일 API를 반환하는 HelloController 클래스를 구성하고, Docker 기반으로 배포할 수 있도록 Dockerfile과 docker-compose.yml 파일을 함께 작성하였습니다.

HelloController.java
@RequestMapping(value = "/v1")  
@RestController  
public class HelloController {  
  
    @GetMapping("/hello")  
    public ResponseEntity<?> helloWorld() {  
        return ResponseEntity.ok("Hello World");  
    }  
  
}

Spring Boot 프로젝트는 Gradle 기반으로 구성되어 있으며, Docker 빌드 시 멀티 스테이지 방식으로 이미지 최적화를 적용했습니다. 먼저 Gradle 이미지에서 애플리케이션을 빌드하고, 그 결과물을 경량화된 JDK 컨테이너에 패키징합니다.

DockerFile
# Build stage  
FROM gradle:jdk21 as build  
WORKDIR /app  
COPY . .  
  
RUN gradle clean build -x test --no-daemon  
  
# Package stage  
FROM openjdk:21-slim  
WORKDIR /app  
COPY --from=build /app/build/libs/*.jar /app/application.jar  
  
EXPOSE 8080  
  
ENTRYPOINT ["java", "-jar", "application.jar"]  
CMD ["--spring.profiles.active=test"]

Coolify에서는 다양한 배포 방식을 지원하지만, 이 글에서는 Docker Compose 기반을 활용하였습니다. 이 방식은 docker-compose.yml 파일을 기준으로 애플리케이션을 정의하고, 그대로 배포할 수 있다는 점에서 구조가 명확하고 유지보수가 용이합니다.

Coolify에서는 docker-compose.yml 파일을 기준으로 서비스를 등록하게 됩니다. 따라서 파일명은 반드시 프로젝트의 실제 설정과 동일하게 유지해야 합니다. 아래는 예시로 작성한 docker-compose.yml입니다.

docker-compose.yml
version: '3.8'  
  
services:  
  coolify-playground:  
    build:  
      context: .  
      dockerfile: Dockerfile  
    image: catsriding/coolify-playground:latest  
    container_name: coolify-playground  
    restart: always  
    ports:  
      - "8070:8080"  
    networks:  
      - coolify  
    environment:  
      TZ: Asia/Seoul  
    command: [ "--spring.profiles.active=prod" ]  
  
networks:  
  coolify:  
    external: true
  • build: 컨테이너 이미지를 빌드할 때 사용할 빌드 컨텍스트(.은 현재 디렉토리를 의미)와 Dockerfile을 지정합니다.
  • image: 빌드된 이미지를 식별할 이름과 태그를 설정합니다. 이 이미지는 이후 재사용될 수 있습니다.
  • ports: 컨테이너 내부의 포트 8080을 호스트의 포트 8070에 매핑하여 외부에서 접근 가능하도록 설정합니다.
  • networks: coolify라는 Docker 네트워크를 참조합니다. 이 네트워크는 Coolify 설치 시 자동으로 생성되며, external: true로 선언함으로써 Docker Compose가 새로 생성하지 않고 기존 네트워크를 그대로 사용하도록 합니다. 이를 통해 Coolify가 관리하는 내부 서비스들(예: 리버스 프록시, 로드 밸런서, SSL 종료 서비스 등)과 원활히 통신할 수 있습니다.
  • environment: 컨테이너 실행 시 필요한 환경 변수를 지정합니다. 예시로 TZ는 시스템의 시간대를 설정하는 변수입니다.
  • command: 기본 실행 명령을 오버라이드하여, 이 경우에는 Spring의 prod 프로파일을 활성화하도록 지정합니다.

작성한 소스코드를 GitHub 저장소에 푸시하면, Coolify가 이를 감지하여 자동으로 빌드 및 배포를 시작할 수 있는 준비가 완료됩니다.

5. GitHub 리포지토리 연동 및 자동 배포 구성 확인하기

이제 Coolify 대시보드로 돌아와, 앞서 연동한 GitHub App을 통해 저장소 목록을 불러옵니다. 만약 리포지토리가 표시되지 않는다면, GitHub App이 해당 저장소에 접근할 수 있도록 GitHub 설정에서 권한을 확인해야 합니다.

5-1. 배포 프로젝트 생성하기

GitHub 저장소를 선택하면 프로젝트 생성 화면으로 이동하며, 코드 변경을 감지할 브랜치, Build Pack 옵션, 그리고 Compose 설정 파일 경로 등을 지정하게 됩니다. 기본적으로 .yaml 확장자가 설정되어 있으나, 개인적으로는 .yml을 선호하여 이를 변경해두었습니다.

automating-spring-boot-application-deployment-with-ci-cd-using-coolify_09.png

5-2. 초기 배포 실행하기

설정을 완료하면 프로젝트 구성 화면으로 진입하게 됩니다. 이곳에서 환경변수 설정, 도메인 연결, 자동 배포 여부 등 세부 항목을 관리할 수 있습니다. 지금은 초기 설정 상태로 배포가 잘 작동하는지만 확인하기 위해, 우측 상단의 Deploy 버튼을 클릭하여 수동 배포를 실행합니다.

automating-spring-boot-application-deployment-with-ci-cd-using-coolify_10.png

5-3. 빌드 및 컨테이너 상태 모니터링하기

Docker Compose 구성을 기반으로 이미지 빌드와 컨테이너 실행이 자동으로 이루어집니다. 로그 화면에서는 빌드 및 배포 상태를 실시간으로 확인할 수 있으며, Debug 로그 활성화 옵션을 사용하면 보다 상세한 정보 확인이 가능합니다. 프로젝트 규모가 커질수록 빌드 시간이 늘어날 수 있으므로, 상황에 따라 빌드 전용 서버를 분리하는 것도 고려해볼 수 있습니다.

automating-spring-boot-application-deployment-with-ci-cd-using-coolify_11.png

5-4. 애플리케이션 엔드포인트 확인하기

빌드가 성공하고 컨테이너가 정상적으로 실행되었다면, 브라우저나 API 테스트 도구를 통해 애플리케이션에 직접 접근할 수 있습니다.

아직 도메인 연결을 하지 않은 상태이므로, Vultr 인스턴스의 퍼블릭 IP 주소에 Docker Compose에서 매핑한 포트를 조합하여 접근해야 합니다. 예를 들어 http://<your-ip>:8070/v1/hello와 같이 호출하면 됩니다.

이 테스트에서는 GET /v1/hello 요청에 대해 문자열 "Hello World"가 정상적으로 반환되는지 확인함으로써, 애플리케이션이 문제없이 배포되었는지를 검증합니다.

automating-spring-boot-application-deployment-with-ci-cd-using-coolify_12.png

5-5. 배포 및 애플리케이션 로그 확인하기

Vultr 인스턴스에 SSH로 접속하여 직접 로그를 확인할 수도 있지만, Coolify는 자체 로그 뷰어를 제공합니다. Logs 탭에서는 각 빌드와 컨테이너 상태, 애플리케이션 로그 등을 실시간으로 확인할 수 있어 운영 편의성이 높습니다.

automating-spring-boot-application-deployment-with-ci-cd-using-coolify_14.png

5-6. 자동 배포 테스트하기

이제 마지막으로, CI/CD가 정상적으로 작동하는지 검증해봅니다. 이를 위해 소스 코드를 간단히 수정한 뒤, GitHub 저장소에 푸시합니다. 예를 들어 Controller의 응답 메시지를 변경하거나 로그 출력을 추가하는 등, 실제 동작에는 영향을 주지 않는 변경을 적용하면 충분합니다.

automating-spring-boot-application-deployment-with-ci-cd-using-coolify_15.png

푸시가 완료되면, Coolify는 GitHub Webhook 이벤트를 감지하여 자동으로 빌드와 배포를 수행합니다. 로그를 확인하면 새로운 커밋에 대해 빌드가 시작되고, 컨테이너가 갱신되는 과정을 실시간으로 추적할 수 있습니다.

변경 사항이 반영된 엔드포인트를 호출해보면, 코드 수정이 실제 서비스에 적용되었는지를 바로 확인할 수 있습니다. 이 과정을 통해 코드 수정 → 커밋 → 푸시 → 자동 배포라는 전체 흐름이 원활하게 동작함을 검증할 수 있습니다.

6. Coolify 운영 편의 기능 구성하기

도메인 설정 역시 Coolify의 강력한 기능 중 하나입니다. 원하는 도메인을 연결하고, Let’s Encrypt 기반으로 SSL 인증서를 자동 발급받아 HTTPS까지 손쉽게 구성할 수 있습니다.

automating-spring-boot-application-deployment-with-ci-cd-using-coolify_13.png

이 외에도 배포 상태에 따른 알림 설정, 빌드 실패 시 자동 재시도, 특정 조건에서의 롤백 처리 등 다양한 운영 편의 기능이 내장되어 있어, 작은 프로젝트라도 안정적으로 배포를 관리할 수 있는 환경을 빠르게 마련할 수 있습니다.

7. 정리하며

이번 글에서는 Vultr 기반 가상 서버에 Coolify를 설치하고, Spring Boot 애플리케이션을 Docker Compose 방식으로 자동 배포하는 과정을 살펴보았습니다. GitHub 연동, 도메인 연결, HTTPS 설정까지 포함한 최소한의 CI/CD 환경을 빠르게 구성할 수 있다는 점은 Coolify의 가장 큰 장점입니다.

Coolify는 Kubernetes 수준의 복잡한 인프라 없이도 자동화된 배포 흐름을 직접 구축할 수 있다는 점에서 간단한 서비스나 개인 프로젝트에 특히 적합합니다. 웹 기반 GUI, 로그 관리, 인증서 자동 발급 등의 기능도 기본적으로 갖추고 있어, 초기 운영 비용을 크게 낮출 수 있습니다.

다만, 고가용성 환경이나 세분화된 배포 전략이 필요한 경우에는 기능상의 제약이 존재하므로 프로젝트 성격에 맞는 판단이 필요합니다.

Coolify는 선배 개발자의 추천으로 처음 접하게 되었는데, 사용해보니 예상보다 훨씬 간편하고 직관적인 도구였습니다. 이후로는 학습용 애플리케이션이나 MVP 수준의 사이드 프로젝트를 배포할 때 꾸준히 활용하고 있으며, 실제 운영 중인 소규모 서비스에도 적용해 만족스러운 결과를 얻고 있습니다.

간단한 구조로 시작하되, 실질적인 운영 자동화를 경험하고자 한다면 Coolify는 충분히 그 첫 선택이 될 수 있습니다. 특히 Git 기반 배포 흐름을 구축해보고자 하는 개발자에게는 좋은 출발점이 되어줄 것입니다.

    Discover more