개요
Coolify는 오픈 소스 셀프 호스팅 플랫폼으로, SSH 연결만으로 자체 서버에 정적 사이트, 풀스택 애플리케이션, 데이터베이스 및 360여 가지 원클릭 서비스를 배포할 수 있습니다. Git 푸시 자동 배포, 프리뷰 환경, 롤백, Webhook, 자동 HTTPS 인증서 및 리버스 프록시를 지원하며 로그 조회와 리소스 모니터링을 제공합니다. 대시보드, API, CLI 및 팀 권한을 통해 리소스를 관리하는 동시에 자신의 인프라를 완전히 제어할 수 있습니다.
README 미리보기
\n\n\n\n# Coolify\n\n**An open-source platform to deploy applications, databases, and services on your own servers.**\n\nOpen source & free forever, backed by our [philosophy](https://coolify.io/philosophy).\n\n\n\n[Website](https://coolify.io) · [Documentation](https://coolify.io/docs) · [Cloud](https://app.coolify.io) · [Discord](https://coollabs.io/discord) · [Community](https://github.com/coollabsio/coolify/discussions)\n\n\n\n## What is Coolify?\n\nCoolify is an open-source and self-hostable alternative to Heroku, Netlify, and Vercel. It helps you manage servers, applications, and databases on your own hardware. You only need an SSH connection.\n\nYou can use a VPS, a bare-metal server, a Raspberry Pi, or any other server that accepts SSH connections. Coolify gives you the convenience of a cloud platform while you keep control of your infrastructure.\n\nYour configurations stay on your servers. If you stop using Coolify, your running resources continue to work and remain manageable.\n\n## What can Coolify do?\n\n- **Deploy any application:** Build from GitHub, GitLab, Bitbucket, or Gitea with Nixpacks, Railpack, Dockerfile, Docker Compose, or a prebuilt Docker image.\n- **Run databases and services:** Deploy managed databases and more than 360 one-click services with persistent storage and generated credentials.\n- **Automate deployments:** Deploy on every Git push, create pull-request previews, call deployment webhooks, and roll back to retained application images.\n- **Manage networking:** Configure custom domains, automatic HTTPS certificates, reverse proxies, health checks, and container networks.\n- **Operate your infrastructure:** Manage multiple servers, inspect deployment and runtime logs, open container terminals, and monitor resource status.\n- **Protect your workloads:** Configure database and storage backups, scheduled tasks, environment variables, secrets, and notifications.\n- **Integrate with your workflow:** Manage resources through the dashboar
FAQ (5)
문제 해결왜 Coolify에서 계속 'DNS mismatch'가 표시되고, 다시 확인해도 DNS 상태가 업데이트되지 않나요?
이는 Coolify의 버그입니다(비동기 DNS 검증 기능과 함께 도입되었으며, 커밋 eb57a691c에서 발생했고 v4.3.23에 존재합니다): checking 상태가 데이터베이스에 저장되지 않기 때문에 DNS 검사를 다시 실행하면 조용히 무시되고, CheckDomainDnsJob이 새 결과를 폐기하여 이전 실패 상태가 영원히 유지됩니다. 해결 방법: 애플리케이션에 저장된 DNS 상태 항목을 지우세요. 가드는 항목이 이미 존재할 때만 적용되므로 새로운 검사가 차단 해제됩니다:
UPDATE applications SET domain_dns_statuses = NULL WHERE id = <id>;그런 다음 도메인 행의 새로 고침 아이콘(또는 'Check All DNS')을 다시 누르세요. 검사가 실행되고 결과가 저장되며 배지가 녹색으로 바뀝니다. 동일한 버그가 서비스 도메인에도 영향을 미칩니다(결함 있는 로직이 app/Livewire/Project/Application/Domains.php와 app/Livewire/Project/Service/Domains.php 두 파일 모두에 존재합니다). 테스트를 포함한 영구적인 수정이 풀 리퀘스트를 통해 제출되고 있으니, 패치된 릴리스가 나오면 Coolify를 업그레이드하세요.
문제 해결Coolify v4.5.0 Docker 이미지에 알려진 보안 권고 사항이 있는 오래된 Nginx 버전이 포함되어 있는 이유는 무엇이며, 이를 어떻게 수정할 수 있습니까?
Coolify v4.5.0은 프로덕션 및 개발 Dockerfiles에서 NGINX_VERSION을 1.31.2-r1로 고정하고 있으며, 이 버전은 공개된 Nginx 보안 권고에 나열되어 있습니다. 다음 명령을 실행하여 이미지 내부에 설치된 버전을 확인할 수 있습니다:
docker run --rm --entrypoint sh coollabsio/coolify:v4.5.0 -c 'nginx -v; apk --no-network info -a nginx'**수정 방법:** Coolify v4.5.1 이상으로 업그레이드하세요. 유지 관리자는 두 Dockerfiles에서 고정된 버전을 1.31.8-r1로 업데이트했으며(커밋 57d75d85d47d2720823b43a700025323774450ad), 다시 빌드된 릴리스 이미지에는 패치된 Nginx 패키지가 포함되어 있습니다. 새 이미지를 가져온 후에는 수동으로 변경할 필요가 없습니다.
참고: Coolify 팀은 취약한 Nginx 기능이 기본 구성에서 사용되지 않음을 확인했으므로, v4.5.0은 기본 상태 그대로는 악용될 수 없습니다. 그러나 공개된 보안 수정 사항을 포함하기 위해 업그레이드하는 것이 여전히 권장됩니다.
문제 해결Coolify "SSH multiplexing failed, falling back to non-multiplexed connection" 및 "ssh -O check exceeded the timeout of 60 seconds" 오류를 해결하는 방법은?
원인 (Coolify ≤4.1.2): SshMultiplexingHelper::masterConnectionExists()가 timeout 래퍼 없이 ssh -O check를 실행하기 때문에, ControlMaster (mux) 소켓이 교착 상태에 빠지면 Laravel의 기본 60초 프로세스 타임아웃이 이를 강제 종료할 때까지 호출이 멈춥니다. 예외는 복구 로직(refreshMultiplexedConnection())이 실행되기 전에 발생하므로, 교착 상태의 mux가 해제되지 않고 해당 서버에 대한 모든 SSH 작업이 무기한으로 매번 60초씩 지연됩니다.
즉각적인 해결 방법 — Coolify 호스트에서 교착 상태의 mux 마스터를 종료하고 남아 있는 소켓을 삭제합니다:
docker exec coolify pkill -f 'ControlPath=/var/www/html/storage/app/ssh/mux'
docker exec coolify rm -f /var/www/html/storage/app/ssh/mux/mux_*그런 다음 배포를 다시 시도하세요. 단순한
docker restart coolify는 교착 상태의 프로세스를 종료하지만 소켓 파일은 남겨두므로 rm도 함께 실행해야 합니다.
문제가 재발하면 패치가 적용될 때까지 SSH 멀티플렉싱을 비활성화하세요: Coolify 환경(.env / docker-compose)에 SSH_MUX_ENABLED=false를 설정하고 Coolify를 재시작하세요. 그러면 멀티플렉싱되지 않은 SSH를 사용하게 되며, 연결당 약간 느려지지만 60초간 멈춘 채 대기하는 일은 없습니다.
영구적인 수정(코드 수준): 확인 명령 앞에 timeout을 붙이고(현재는 isConnectionHealthy()만 보호하고 있는 기존 SSH_MUX_HEALTH_CHECK_TIMEOUT, 기본값 5초를 재사용) ensureMultiplexedConnection()에서 connectionIsReusable() 호출을 try/catch 안으로 이동하여, 타임아웃된 마스터가 예외로 빠져나가는 대신 복구를 트리거하도록 합니다. issue #11130을 추적하고 수정이 릴리스되면 Coolify를 업그레이드하세요.
문제 해결인스턴스가 Cloudflare 뒤에 있을 때 Coolify의 API IP allowlist가 "You are not allowed to access the API"를 반환하는 이유는 무엇인가요?
근본 원인: Coolify의 TrustProxies 미들웨어가 $proxies = '*'를 하드코딩하는데, Laravel에서는 이 설정이 직접 연결(내장 Traefik/coolify-proxy)만 신뢰합니다. Traefik이 Cloudflare 엣지 IP를 X-Forwarded-For에 추가하므로, request()->ip()가 실제 클라이언트가 아닌 Cloudflare 엣지 IP로 확인됩니다. 따라서 허용 목록 항목(예: Anthropic의 160.79.104.0/21)은 절대 일치할 수 없으며, 감사 로그에도 엣지 IP가 기록됩니다. 해결 방법:
1. Cloudflare를 우회하여 오리진에 직접 쿼리합니다: curl -s --resolve your-domain.com:443:<origin-ip> https://your-domain.com/api/v1/version -H "Authorization: Bearer <token>"
2. Cloudflare에서 인스턴스 도메인을 DNS-only(회색 구름)로 설정하여 실제 클라이언트 IP가 Coolify에 도달하도록 합니다.
3. Settings → Advanced에서 "Allowed IPs for API Access"를 일시적으로 비웁니다 — 이렇게 하면 /api/v1/* 및 /mcp 접근이 복원되지만 IP 제한이 제거되므로 임시 조치로만 사용하세요.
Cloudflare의 IP 범위를 화이트리스트에 추가하지 마세요 — 그렇게 하면 Cloudflare 프록시를 경유하는 모든 클라이언트가 허용됩니다. 영구적인 수정 사항(Cloudflare가 공개한 CIDR을 명시적으로 신뢰하는 옵트인 TRUSTED_PROXIES 설정)이 해당 이슈에서 제안되었습니다. 최신 Coolify 릴리스로 업그레이드하고 변경 로그에서 해당 기능 포함 여부를 확인하세요.
문제 해결Coolify에서 Nixpacks에서 Railpack으로 전환한 후 PayloadCMS 빌드가 'getaddrinfo ENOTFOUND' 또는 MongoDB 연결 타임아웃으로 실패하는 이유는 무엇인가요?
근본 원인: Coolify의 Railpack 빌드는 docker-container 드라이버를 사용하는 docker buildx를 통해 실행되므로, 빌드가 격리된 BuildKit 빌더 컨테이너 내부에서 수행됩니다. 이 빌더는 Coolify의 내부 Docker 네트워크(10.0.1.x)에 연결되어 있지 않으며, --network host는 Docker 호스트가 아닌 빌더 컨테이너의 네임스페이스에만 적용됩니다. 따라서 --add-host 항목으로는 MongoDB 컨테이너에 도달할 수 없어 MongooseServerSelectionError: getaddrinfo ENOTFOUND <hostname> 오류가 발생하거나, 컨테이너 IP(예: 10.0.1.6)를 직접 사용하는 경우 30초 연결 타임아웃이 발생합니다.
해결 방법:
1. 빠른 해결책: Coolify의 서비스 설정에서 Build Pack을 Nixpacks로 되돌리세요. 기존 방식의 docker build는 실제 호스트 네트워킹으로 실행되므로, 빌드 시 Coolify 내부 네트워크와 데이터베이스 컨테이너에 접근할 수 있습니다.
2. 권장 해결책: 빌드 시점의 데이터베이스 의존성을 완전히 제거하세요 — PayloadCMS/Next.js는 런타임에만 MongoDB를 필요로 해야 합니다. Payload를 쿼리하는 페이지/레이아웃에 export const dynamic = 'force-dynamic'을 추가하거나(또는 DB 호출을 지연시켜) next build가 정적 생성 중에 더 이상 MongoDB에 연결하지 않도록 하세요. 그러면 데이터베이스 접근 없이도 Railpack에서 빌드가 성공합니다.