Ubuntu 22.04 환경에서 Coolify PaaS 구축하는 방법

핵심 요약: 본 문서는 자체 호스팅 PaaS(Platform as a Service) 솔루션인 Coolify의 설치, 초기 관리자 설정, 그리고 핵심 메뉴(서버, 소스, 목적지, 프로젝트, 애플리케이션, 데이터베이스 등)의 기능과 사용법을 단계별로 상세히 설명한다. 이 가이드를 통해 사용자는 Coolify의 기본 아키텍처를 이해하고 자신의 애플리케이션을 직접 배포 및 관리할 수 있는 역량을 갖추게 된다.

클라우드 네이티브 시대에 접어들면서, 개발자들은 인프라 관리의 복잡성에서 벗어나 비즈니스 로직 개발에 집중하기를 원한다. Heroku, Vercel, Netlify와 같은 PaaS 플랫폼은 이러한 요구에 부응하며 많은 사랑을 받고 있다. 그러나 특정 클라우드에 대한 종속성이나 비용 문제로 인해 자체 서버에 유사한 환경을 구축하고자 하는 수요 역시 꾸준히 증가하고 있다. Coolify는 바로 이러한 목적을 위한 오픈소스 솔루션으로, 개인 서버에 몇 분 만에 완전한 기능을 갖춘 PaaS를 구축할 수 있도록 지원한다.

본 문서는 Coolify를 처음 접하는 사용자를 대상으로, 초기 설치부터 주요 기능들을 활용하여 실제 웹 애플리케이션을 배포하는 전 과정을 명확하고 상세한 절차에 따라 안내하는 것을 목표로 한다.

0. 시작 전 준비 사항

본 튜토리얼을 진행하기에 앞서, 아래의 환경이 준비되어 있는지 확인해야 한다. Coolify는 다양한 환경에 설치 가능하지만, 본 문서는 가장 일반적인 클라우드 VPS(가상 사설 서버) 환경을 기준으로 설명한다.

• 서버: 공개 IP 주소를 가진 Ubuntu 22.04 LTS 서버 (최소 2-core CPU, 2GB RAM 권장)
• SSH 접속: 해당 서버에 SSH로 접속할 수 있는 권한
• Docker 및 Docker Compose: 서버에 v20.10 이상 버전 설치 (docker --version 명령어로 확인)
• 도메인 (선택 사항): 배포할 애플리케이션에 연결할 개인 도메인
• GitHub 계정: 소스 코드를 가져올 GitHub 계정

모든 요구사항이 충족되었다면, SSH를 통해 서버에 접속하여 설치를 진행할 준비를 마친다.

1단계: Coolify 설치

Coolify 설치는 놀라울 정도로 간단하다. 공식 문서에서 제공하는 단 한 줄의 명령어로 모든 과정이 완료된다. 서버의 터미널에 아래 명령어를 입력하여 실행한다.

wget -q https://get.coollabs.io/coolify/install.sh -O install.sh; sudo bash ./install.sh

위 스크립트는 Coolify 구동에 필요한 Docker 이미지들을 내려받고, 설정 파일을 생성하며, 관련 컨테이너들을 실행하는 모든 작업을 자동으로 처리한다. 설치 과정에서 몇 가지 질문이 나타날 수 있으나, 대부분 기본값으로 진행해도 무방하다.

설치가 정상적으로 완료되면, Coolify 인스턴스에 접속할 수 있는 주소와 초기 관리자 계정 생성 안내가 터미널에 출력된다. 일반적으로 http://<서버_공개_IP>:8000 주소로 웹 브라우저를 통해 접속할 수 있다.

웹 브라우저로 해당 주소에 접속하여 아래와 같은 등록 화면이 나타나면 성공적으로 설치된 것이다.

최초 접속 시 관리자 계정 등록 화면

안내에 따라 Email, Password를 입력하여 관리자 계정을 생성한다. 이 계정은 Coolify 인스턴스 전체를 관리하는 최상위 권한을 가진다.

2단계: 핵심 메뉴 구조 이해하기

로그인 후 처음 마주하는 대시보드는 다소 생소할 수 있다. 효과적인 사용을 위해 Coolify의 핵심 메뉴 구조를 먼저 이해하는 것이 중요하다. 좌측 사이드바에는 주요 기능들이 메뉴 형태로 나열되어 있다.

Coolify의 메인 대시보드와 좌측 메뉴

• Projects (프로젝트): 애플리케이션, 데이터베이스 등 관련된 리소스들을 그룹화하는 최상위 단위.
• Servers (서버): Coolify가 관리하는 물리적 또는 가상 서버의 목록.
• Destinations (목적지): 배포된 리소스가 실제로 실행될 환경. 일반적으로 Docker 컨테이너 또는 Kubernetes 클러스터를 의미한다.
• Sources (소스): Git 리포지토리 제공자(GitHub, GitLab 등)를 연동하는 메뉴.
• Settings (설정): Coolify 인스턴스 전반에 대한 설정.

📌 아키텍처 이해하기
Coolify의 리소스 관리 흐름은 Source → Project → Destination 순으로 이해하면 명확하다. 즉, 'Source(GitHub)에서 코드를 가져와서, Project(논리적 그룹) 내의 애플리케이션으로 빌드한 후, Destination(서버의 Docker)에 배포한다'는 개념이다.

3단계: 메뉴별 상세 기능 및 설정

이제 각 메뉴에 진입하여 실제 배포를 위한 설정들을 단계별로 진행한다. 가장 먼저 소스코드 연동부터 시작한다.

3.1. Sources: GitHub 연동하기

애플리케이션을 배포하려면 코드가 저장된 Git 리포지토리에 Coolify가 접근할 수 있어야 한다. 이를 위해 GitHub App을 생성하고 Coolify에 등록하는 과정이 필요하다.

1. 좌측 메뉴에서 'Sources'를 클릭한 후, 'GitHub Apps' 탭을 선택한다.
2. 화면에 표시된 'Create a new GitHub App' 링크를 클릭하여 GitHub 앱 생성 페이지로 이동한다.
3. 'GitHub App name'을 적절히 입력한다 (예: my-coolify-app).
4. 'Homepage URL'에는 http://<서버_공개_IP>:8000을 입력한다.
5. 'Webhook' 섹션에서 'Active' 체크박스를 활성화한다. 'Webhook URL'과 'Webhook secret'은 Coolify 화면에 표시된 값을 그대로 복사하여 붙여넣는다.
6. 'Permissions' 설정은 매우 중요하다. 'Repository permissions'에서 아래 항목들에 'Read & write' 권한을 부여한다:
   • Administration
   • Checks
   • Contents
   • Deployments
   • Metadata (Read-only)
   • Pull requests
   • Webhooks
7. 페이지 하단의 'Where can this GitHub App be installed?'에서 'Any account'를 선택하고 'Create GitHub App' 버튼을 클릭한다.
8. 생성된 앱의 설정 페이지에서 'Generate a private key' 버튼을 클릭하여 .pem 파일을 다운로드한다.
9. 다시 Coolify의 'Sources' 화면으로 돌아와, 'App ID', 'Client ID', 'Client Secret', 'Private Key' 등 GitHub 앱 페이지에 표시된 정보들을 각 필드에 맞게 입력하고 저장한다.

이 과정이 완료되면, Coolify는 해당 GitHub App이 설치된 리포지토리에 접근할 권한을 얻게 된다.

🧐 오류 해결 (Troubleshooting)
GitHub 연동 후 리포지토리 목록이 보이지 않는다면, 대부분 권한 문제이다. GitHub App 설정에서 Permissions가 올바르게 부여되었는지, 그리고 해당 App을 본인의 GitHub 계정 또는 조직에 'Install' 했는지 다시 한번 확인해야 한다.

3.2. Servers & Destinations

'Servers' 메뉴를 클릭하면, 현재 Coolify가 설치된 로컬 서버가 'localhost'라는 이름으로 이미 등록되어 있는 것을 볼 수 있다. 이 메뉴에서는 Coolify가 관리할 원격 서버를 추가할 수도 있으나, 초기 단계에서는 로컬 서버만으로 충분하다.

'Destinations'는 배포가 이루어질 종착지를 의미한다. 기본적으로 'localhost' 서버 내의 Docker 엔진이 'Local Docker Engine'이라는 이름의 목적지로 자동 설정되어 있다. 따라서 별도의 설정 없이도 로컬 서버의 Docker 환경에 애플리케이션을 즉시 배포할 수 있다.

3.3. Projects: 배포 공간 생성

이제 실제 배포를 진행할 공간인 'Project'를 생성한다. 하나의 프로젝트는 여러 개의 애플리케이션과 데이터베이스를 담는 컨테이너 역할을 한다.

1. 좌측 메뉴에서 'Projects'를 클릭하고, '+ New' 버튼을 눌러 새 프로젝트를 생성한다.
2. 프로젝트 이름(예: 'My First App')을 입력하고 'Create'를 클릭한다.
3. 생성된 프로젝트를 클릭하면, 'Environments'가 나타난다. 기본으로 'production' 환경이 생성되어 있다. 필요에 따라 'staging', 'development' 등 추가 환경을 만들 수 있다.

이제 'production' 환경으로 진입하여 리소스를 추가할 준비를 마친다.

3.4. Application & Database: 리소스 배포하기

프로젝트 환경 내에서 '+ New' 버튼을 클릭하면, 배포할 수 있는 다양한 리소스 유형이 나타난다. 여기서는 가장 대표적인 'Application'과 'PostgreSQL Database'를 배포해본다.

애플리케이션 배포 (Application)

1. 리소스 추가 화면에서 'Application'을 선택한다.
2. 앞서 설정한 GitHub 소스를 선택하고, 배포하고자 하는 리포지토리와 브랜치를 선택한다.
3. 'Build Pack'은 대부분의 경우 'Nixpacks'를 선택하면 된다. Nixpacks는 리포지토리의 코드를 분석하여 Node.js, Python, Go 등 언어와 프레임워크를 자동으로 감지하고 빌드해주는 강력한 도구이다.
4. 'Port'에는 애플리케이션이 내부적으로 사용하는 포트 번호를 입력한다 (예: Node.js Express의 경우 3000, React의 경우 3000 등).
5. 'Save configuration'을 클릭하여 애플리케이션 리소스를 생성한다.

리소스가 생성되면 세부 설정 페이지로 이동한다. 여기서 도메인 연결, 환경 변수 설정, 빌드/실행 명령어 수정 등 다양한 작업을 수행할 수 있다.

• General: FQDN(정식 도메인 주소)을 입력하면 Coolify가 자동으로 리버스 프록시와 SSL 인증서(Let's Encrypt)를 설정해준다.
• Environment Variables: DATABASE_URL, API_KEY와 같은 민감한 정보를 안전하게 주입할 수 있다.
• Deployments: 'Deploy' 버튼을 눌러 수동으로 배포를 트리거하거나, Webhook 설정을 통해 Git push 시 자동 배포가 이루어지도록 할 수 있다.

데이터베이스 생성 (PostgreSQL Database)

애플리케이션이 데이터베이스를 필요로 할 경우, Coolify를 통해 손쉽게 생성할 수 있다.

1. 리소스 추가 화면에서 'PostgreSQL Database'를 선택한다.
2. 이름과 데이터베이스 사용자/비밀번호를 설정하고 'Save configuration'을 클릭하면 즉시 PostgreSQL 컨테이너가 생성된다.
3. 생성된 데이터베이스 리소스의 'General' 탭에서 외부 접속을 허용하거나, 내부 네트워크에서만 사용 가능한 연결 URL을 확인할 수 있다. 이 URL을 복사하여 애플리케이션의 DATABASE_URL 환경 변수에 붙여넣으면 된다.

'Deploy' 버튼 클릭 후 실시간으로 빌드 및 배포 로그를 확인할 수 있다.

결론

이상으로 자체 호스팅 PaaS인 Coolify의 설치부터 초기 설정, 그리고 핵심 메뉴들의 기능과 실제 애플리케이션 배포 과정까지 상세히 살펴보았다. Coolify는 복잡한 인프라 설정과 배포 파이프라인 구축 작업을 추상화하여, 개발자가 코드에만 집중할 수 있는 환경을 제공한다. 특히 개인 프로젝트나 소규모 팀에게는 클라우드 서비스의 훌륭한 대안이 될 수 있다.

본 튜토리얼에서 다룬 내용은 Coolify가 제공하는 기능의 일부에 불과하다. 사용자는 본 가이드를 바탕으로 원격 서버 추가, Kubernetes 클러스터 연동, 서비스(Service) 메뉴를 통한 Redis나 MongoDB 등 추가 미들웨어 배포 등 더욱 다양한 활용법을 탐색해 볼 수 있을 것이다.