Coolify: 셀프호스팅 Heroku/Vercel 대안 오픈소스 PaaS 플랫폼 설치 가이드 ⋆ Blog * JackerLab

개요

Coolify는 오픈소스 셀프호스팅 PaaS(Platform as a Service) 플랫폼입니다. Apache 2.0 라이선스로 배포되며, 35K+ GitHub Stars를 보유하고 있습니다. Heroku, Vercel, Netlify의 완전한 대안으로, Git 푸시만으로 앱을 자동 배포하고, 280+ 원클릭 서비스를 제공합니다. 모든 기능이 무료이며, 벤더 락인 없이 자신의 서버에서 운영할 수 있습니다.

Coolify의 핵심 철학

Coolify의 슬로건은 **”클라우드의 편리함을 자신의 서버에서”**입니다. Docker, 리버스 프록시, SSL, CI/CD를 직접 설정하는 대신, Coolify 하나로 모든 것을 해결합니다. 서버에 SSH 접속만 가능하면 VPS, 베어메탈, 라즈베리파이 어디든 배포할 수 있습니다.

왜 Coolify인가?

기존 방식의 문제점

앱을 배포하려면...
1. 서버 구매 및 OS 설치
2. Docker 설치 및 설정
3. Nginx/Traefik 리버스 프록시 설정
4. Let's Encrypt SSL 인증서 발급
5. CI/CD 파이프라인 구축 (GitHub Actions 등)
6. 데이터베이스 설치 및 설정
7. 환경 변수 관리
8. 로그 및 모니터링 설정
... 😩 수일~수주 소요

Coolify 사용 시

1. Coolify 설치 (5분)
2. Git 저장소 연결
3. 배포 버튼 클릭
→ 끝! 🎉 (자동으로 빌드, SSL, 도메인 설정)

주요 특징

기능	설명
Git 자동 배포	GitHub/GitLab/Bitbucket 푸시 시 자동 배포
280+ 원클릭 서비스	WordPress, Ghost, Supabase, n8n 등 즉시 배포
원클릭 데이터베이스	PostgreSQL, MySQL, MongoDB, Redis 등
자동 SSL	Let’s Encrypt 자동 발급/갱신
자동 리버스 프록시	Traefik 내장
멀티 서버 관리	여러 서버를 하나의 대시보드에서 관리
Docker Compose 지원	기존 docker-compose.yml 그대로 배포
프리뷰 배포	PR마다 임시 환경 자동 생성
S3 백업	S3 호환 스토리지로 자동 백업
Webhook	빌드/배포 이벤트 알림
API	REST API로 자동화
Docker Swarm	클러스터 배포 지원 (K8s 예정)
Nixpacks	Dockerfile 없이 자동 빌드
벤더 락인 없음	모든 설정이 서버에 저장

지원 프레임워크 및 언어

카테고리	지원 항목
프론트엔드	Next.js, Nuxt.js, React, Vue, Svelte, Astro, Gatsby
백엔드	Node.js, Python, Go, Rust, PHP, Ruby, Java
정적 사이트	HTML/CSS/JS, Hugo, Jekyll, 11ty
풀스택	Laravel, Rails, Django, FastAPI, NestJS
기타	Dockerfile, Docker Compose, Docker 이미지

원클릭 서비스 (일부)

카테고리	서비스
CMS/블로그	WordPress, Ghost, Strapi, Directus
분석	Plausible, Umami, Matomo, PostHog
자동화	n8n, Activepieces, Huginn
데이터베이스	PostgreSQL, MySQL, MongoDB, Redis, ClickHouse
개발 도구	Gitea, GitLab, VS Code Server, Hoppscotch
모니터링	Uptime Kuma, Grafana, Prometheus
보안	Vaultwarden, Authentik, Keycloak
생산성	Nextcloud, Outline, Memos, AppFlowy
미디어	Jellyfin, Plex, Immich, PhotoPrism
기타	Supabase, Appwrite, Minio, RabbitMQ

전체 280+ 서비스 목록: coolify.io/docs/services

PaaS 플랫폼 비교

기능	Coolify	Heroku	Vercel	Netlify	Railway
셀프호스팅	✅	❌	❌	❌	❌
오픈소스	✅	❌	❌	❌	❌
무료 (셀프호스팅)	✅ 완전 무료	❌	❌	❌	❌
Docker 지원	✅	✅	❌	❌	✅
데이터베이스	✅ 내장	애드온	❌	❌	✅
멀티 서버	✅	❌	❌	❌	❌
자동 SSL	✅	✅	✅	✅	✅
Git 자동 배포	✅	✅	✅	✅	✅
벤더 락인	❌ 없음	✅	✅	✅	✅
비용 (월)	$0 + 서버비	$7~$25+/앱	$20+/user	$19+/user	$5+/서비스

시스템 요구 사항

Coolify 서버 (관리 서버)

항목	최소 사양	권장 사양
CPU	2 코어	4 코어
RAM	2GB	4GB 이상
저장소	30GB	50GB 이상 (SSD)
OS	Ubuntu 22.04/24.04, Debian 11/12	Ubuntu 24.04 LTS

지원 OS

OS	상태
Ubuntu 22.04 LTS	✅ 권장
Ubuntu 24.04 LTS	✅ 권장
Debian 11	✅
Debian 12	✅
Raspberry Pi OS (64-bit)	✅
CentOS/RHEL	⚠️ 제한적

필수 포트

포트	용도
22	SSH
80	HTTP
443	HTTPS
8000	Coolify UI (초기 설정용)

설치

원클릭 설치 (권장)

curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash

이 명령어 하나로:

Docker 자동 설치
Docker Compose 설치
Traefik 프록시 설정
Coolify 대시보드 실행
SSH 키 생성

설치 옵션

# 커스텀 설정으로 설치
env ROOT_USERNAME=admin \
    ROOT_USER_EMAIL=admin@example.com \
    ROOT_USER_PASSWORD=SecurePassword123 \
    AUTOUPDATE=false \
    bash -c 'curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash'

수동 설치

# 1. 디렉토리 생성
mkdir -p /data/coolify/{source,ssh,applications,databases,backups,services,proxy,webhooks-during-maintenance}
mkdir -p /data/coolify/ssh/{keys,mux}
mkdir -p /data/coolify/proxy/dynamic

# 2. SSH 키 생성
ssh-keygen -t ed25519 -a 100 -f /data/coolify/ssh/keys/id.root@host.docker.internal -q -N "" -C root@coolify

# 3. SSH 키 등록
cat /data/coolify/ssh/keys/id.root@host.docker.internal.pub >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

# 4. 설정 파일 다운로드
curl -fsSL https://cdn.coollabs.io/coolify/docker-compose.yml -o /data/coolify/source/docker-compose.yml
curl -fsSL https://cdn.coollabs.io/coolify/docker-compose.prod.yml -o /data/coolify/source/docker-compose.prod.yml
curl -fsSL https://cdn.coollabs.io/coolify/.env.production -o /data/coolify/source/.env

# 5. 실행
cd /data/coolify/source
docker compose --env-file /data/coolify/source/.env \
  -f /data/coolify/source/docker-compose.yml \
  -f /data/coolify/source/docker-compose.prod.yml \
  up -d --pull always --remove-orphans --force-recreate

설치 확인

# 컨테이너 상태 확인
docker ps | grep coolify

# 로그 확인
docker logs coolify -f

초기 설정

1) 웹 UI 접속

브라우저에서 http://서버IP:8000으로 접속합니다.

2) 관리자 계정 생성

이메일 입력
비밀번호 설정 (8자 이상)
Register 클릭

3) 첫 번째 프로젝트 생성

+ New Project 클릭
프로젝트 이름 입력 (예: my-website)
환경 생성 (Production, Staging 등)

앱 배포 가이드

방법 1: Git 저장소에서 배포

1. Projects > 프로젝트 선택 > + New Resource
2. "Public Repository" 또는 "Private Repository" 선택
3. GitHub/GitLab 연동 또는 URL 직접 입력
4. 빌드 설정:
   - Build Pack: Nixpacks (자동 감지) 또는 Dockerfile
   - Branch: main
   - Port: 3000 (앱에 따라 다름)
5. 도메인 설정 (선택)
6. Deploy 클릭!

방법 2: Docker 이미지 배포

1. + New Resource > "Docker Image"
2. 이미지 입력: nginx:latest
3. 포트 설정: 80
4. 환경 변수 설정 (필요시)
5. Deploy 클릭

방법 3: Docker Compose 배포

1. + New Resource > "Docker Compose Empty"
2. docker-compose.yml 내용 붙여넣기
3. 환경 변수 설정
4. Deploy 클릭

예시 docker-compose.yml:

services:
  web:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./html:/usr/share/nginx/html

  api:
    build: ./api
    environment:
      - DATABASE_URL=${DATABASE_URL:?}
    depends_on:
      - db

  db:
    image: postgres:15
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD:-secret}
    volumes:
      - db_data:/var/lib/postgresql/data

volumes:
  db_data:

방법 4: 원클릭 서비스 배포

1. + New Resource > "Service"
2. 카테고리에서 서비스 선택 (예: WordPress)
3. 자동으로 설정된 환경 변수 확인
4. Deploy 클릭
→ 수분 내에 완전히 작동하는 서비스 배포 완료!

데이터베이스 배포

PostgreSQL 배포

1. + New Resource > "Database"
2. PostgreSQL 선택
3. 설정:
   - Version: 15 또는 16
   - Database: myapp
   - Username: myuser
   - Password: (자동 생성 또는 직접 입력)
4. Deploy 클릭

데이터베이스 연결

배포된 데이터베이스의 연결 정보:

Host: <database-uuid>
Port: 5432
Database: myapp
Username: myuser
Password: ********

# 내부 연결 (같은 프로젝트 내 앱에서)
DATABASE_URL=postgresql://myuser:password@<database-uuid>:5432/myapp

# 외부 연결 (Public 활성화 시)
DATABASE_URL=postgresql://myuser:password@db.yourdomain.com:5432/myapp

도메인 및 SSL 설정

커스텀 도메인 연결

DNS 설정: myapp.example.com A → Coolify 서버 IP
Coolify에서: 앱 선택 > Settings > Domains 도메인 입력: myapp.example.com Save
SSL 인증서가 자동으로 발급됩니다.

와일드카드 도메인

*.example.com  A  → Coolify 서버 IP

Coolify가 자동으로 서브도메인 라우팅을 처리합니다.

Git 자동 배포 설정

GitHub 연동

Settings > Git Providers > GitHub
GitHub App 생성 또는 OAuth 연동
저장소 접근 권한 부여

자동 배포 트리거

앱 선택 > Settings > Git
- Auto Deploy: 활성화
- Branch: main
- Webhook Secret: (자동 생성)

이제 main 브랜치에 푸시할 때마다 자동 배포됩니다.

PR 프리뷰 배포

Settings > Pull Request Previews: 활성화

PR이 생성되면 자동으로 임시 환경이 배포되고, PR이 닫히면 자동 삭제됩니다.

멀티 서버 관리

추가 서버 연결

Servers > + Add Server
서버 정보 입력:
- Name: production-server
- IP: 203.0.113.2
- SSH Port: 22
- User: root
SSH 키 복사 후 대상 서버에 등록
Validate Server 클릭

서버별 배포

앱 생성 시:
- Destination: production-server 선택

환경 변수 관리

앱별 환경 변수

앱 선택 > Environment Variables
+ Add Variable:
  - Key: DATABASE_URL
  - Value: postgresql://...
  - Is Secret: ✅ (민감 정보)

공유 환경 변수

프로젝트 레벨에서 여러 앱이 공유:

Project > Shared Variables
+ Add:
  - Key: API_KEY
  - Value: sk-xxx...

앱에서 사용:

environment:
  - API_KEY=${API_KEY}

백업 설정

S3 백업 구성

Settings > Backup
S3 정보 입력:
- Endpoint: s3.amazonaws.com (또는 MinIO 등)
- Bucket: coolify-backups
- Access Key: AKIA…
- Secret Key: ********
- Region: us-east-1
Test Connection > Save

데이터베이스 백업

Database > Settings > Scheduled Backups
- Frequency: Daily
- Time: 03:00 UTC
- Retention: 7 days

트러블슈팅

배포 실패

# 빌드 로그 확인
Coolify UI > 앱 > Deployments > 실패한 배포 클릭

# Docker 로그 확인
docker logs <container-name>

# Traefik 로그
docker logs coolify-proxy

SSL 인증서 발급 실패

DNS 설정 확인: dig myapp.example.com +short # Coolify 서버 IP가 표시되어야 함
포트 80/443 방화벽 확인: sudo ufw allow 80 sudo ufw allow 443
Let’s Encrypt 로그: docker logs coolify-proxy 2>&1 | grep -i acme

컨테이너 접속

# 실행 중인 컨테이너 목록
docker ps

# 컨테이너 쉘 접속
docker exec -it <container-name> sh

Coolify 재시작

cd /data/coolify/source
docker compose down
docker compose up -d

업데이트

자동 업데이트

Coolify는 기본적으로 자동 업데이트됩니다.

비활성화하려면:

Settings > Auto Update: 비활성화

수동 업데이트

cd /data/coolify/source
docker compose pull
docker compose up -d --remove-orphans

버전 확인

Settings > About > Version

모니터링

내장 모니터링

Dashboard: CPU, 메모리, 디스크 사용량
Logs: 실시간 앱 로그
Deployments: 배포 히스토리

외부 모니터링 연동

Prometheus metrics 엔드포인트:

https://coolify.yourdomain.com/metrics

Grafana 대시보드와 연동 가능합니다.

가격 정책

플랜	가격	설명
Self-hosted	$0	완전 무료, 모든 기능 포함
Cloud	$5/월~	Coolify 팀이 관리, 서버는 직접 연결

셀프호스팅 시 서버 비용만 발생 (Hetzner 기준 월 $4~5)

💡 사용 사례

1. 개인 개발자

사이드 프로젝트 무료 배포
포트폴리오 사이트 호스팅

2. 스타트업

Heroku 비용 절감 (월 $500+ → $20)
프로덕션 + 스테이징 환경 분리

3. 에이전시

클라이언트별 프로젝트 관리
멀티 서버로 리소스 분리

4. 기업

내부 도구 프라이빗 배포
데이터 주권 확보 (GDPR 등)

개요