로컬 개발 환경에서 문제없이 동작하던 백엔드와 데이터베이스를 클라우드엔지니어님이 제공해주신 환경으로 이전하는 작업을 진행하였습니다.
이번 글에서는 Coolify를 처음 전달받은 상황부터, DB 연동 → 백엔드 배포 → 자동 배포(Webhook) → 마이그레이션 자동화까지
실제로 설정하며 확인한 기준과 이유를 정리합니다.
Coolify는 무엇이며, 어떤 위치의 서비스인가
클라우드 엔지니어로부터 다음과 같은 관리자 페이지를 전달받았습니다.
이는 EC2 인스턴스 자체가 아니라,
EC2 위에 설치된 Coolify 관리자 콘솔입니다.
정리하면 구조는 다음과 같습니다.
- EC2 인스턴스: 인프라 레벨 (클라우드 엔지니어가 관리)
- Coolify: EC2 위에서 동작하는 서버 관리 및 배포 플랫폼
- 백엔드 / DB: Coolify를 통해 생성·관리되는 컨테이너 서비스
즉, 저는 EC2에 직접 SSH로 접근하거나
Docker, 네트워크를 직접 구성하지 않고,
Coolify UI를 통해 서비스 단위로 관리하는 역할입니다.
이전 목표: “로컬에서 하던 것을 서버에서도 그대로”
이전의 목표는 단순합니다.
- 로컬에서 사용하던 백엔드(Express + TypeScript)
- MySQL 데이터베이스
- Sequelize ORM
이 조합을 서버에서도 동일하게 동작하도록 이전하는 것입니다.
Coolify는 이 목적에 적합한 도구였습니다.
DB를 먼저 생성해야 하는 이유
처음에는 백엔드부터 배포하려 했으나,
실제로는 DB를 먼저 생성하는 것이 훨씬 안정적입니다.
Coolify에서 Databases 메뉴를 통해 MySQL을 생성하면 다음 정보가 자동으로 제공됩니다.
- DB_NAME
- DB_USER
- DB_PASSWORD
- DB_PORT
- DB_HOST
이 중 가장 중요한 값은 DB_HOST입니다.
DB_HOST 값이 왜 이렇게 생겼는가
실제 설정된 값은 다음과 같습니다.
이 값은 MySQL의 고유 ID도 아니고, 계정 ID도 아닙니다.
이 값의 정체는 Coolify가 생성한 DB 컨테이너의 내부 hostname입니다.
Coolify는 데이터베이스 컨테이너를 생성할 때 Docker 내부 네트워크에서 유일한 서비스 식별자를 hostname으로 부여합니다.
따라서 사람이 읽기 쉬운 mysql이나 db가 아니라
고유한 문자열 형태로 생성될 수 있습니다.
왜 DB_HOST에 이 값을 사용해야 하는가?
Coolify 내부에서는 다음과 같은 구조로 동작합니다.
- 백엔드 컨테이너
- DB 컨테이너
이 두 컨테이너는 동일한 Docker 네트워크에 속해 있습니다.
이 환경에서는 다음과 같은 규칙이 적용됩니다.
- localhost: 현재 컨테이너 자신을 의미합니다.
- 퍼블릭 IP: 외부 접근용이며 내부 통신에는 불필요합니다.
- 컨테이너 hostname: 내부 통신의 정식 접근 방식입니다.
따라서 DB_HOST는 다음과 같이 설정하는 것이 올바릅니다.
퍼블릭 IP를 사용하지 않기 때문에
- DB 외부 노출이 필요 없고
- 방화벽 설정이 단순하며
- 보안과 성능 면에서 유리합니다
백엔드 레포지토리 연결 및 환경변수 설정
Applications 메뉴에서 GitHub 레포지토리를 연결한 후 로컬 .env에서 사용하던 값을 그대로 Coolify 환경변수로 옮깁니다.
여기서 혼동하기 쉬운 부분은 DB 엔드포인트는 백엔드 앱이 아니라 Database 서비스 화면에서 확인한다는 점입니다.
백엔드는 DB를 관리하지 않고, 단순히 연결해서 사용하는 주체입니다.
또한 참고로 레포지토리 접근은 Public으로 하는게 더 좋답니다.
연결 확인 기준
다음 조건이 충족되면 DB 연결은 정상입니다.
- 백엔드 컨테이너 상태: 정상(초록)
- DB 컨테이너 상태: 정상(초록)
- DB 컨테이너 내부에서 show tables; 실행 시 테이블 조회 가능
이 상태에서 문제가 발생한다면
대부분 다음 중 하나입니다.
- DB_HOST 오입력 -> 대부분 여기가 문제이더군요..
- 환경변수 이름 오타
- 코드에서 설정 파일 로딩 오류
Github Repository Webhook을 설정해야 하는 이유
Deploy 버튼으로 수동 배포도 가능하지만,
지속적인 개발 환경에서는 불편합니다.
GitHub에 push 후 자동으로 배포되도록
Webhook을 설정하는 것이 필수적입니다.
주의할 점은 다음과 같습니다.
- Webhook은 DB가 아니라 Application(백엔드 앱) 에 설정합니다.
- 배포의 주체는 데이터베이스가 아니라 애플리케이션이기 때문입니다.
Webhook 설정 후에는
push → 자동 빌드 → 자동 배포 흐름이 완성됩니다.
마이그레이션 자동화가 핵심입니다 (CI/CD 자동화)
가장 많이 헷갈리는 지점은 다음입니다.
코드 변경 후 배포했는데 DB 스키마가 바뀌지 않는다.
이는 정상적인 동작입니다.
코드 변경만으로 DB는 변경되지 않기 때문입니다.
물론 메인브랜치에 Push를 하고 수동으로 Coolify BE 터미널에서 아래 명령을 직접 넣어주는 것도 관계없으나
불편하겠습니다.
따라서 로컬에서는 직접 실행하던 다음 명령을
Coolify에서는 Post-deployment command에 등록합니다.
이제 배포 흐름은 다음과 같이 정리됩니다.
- 엔티티 추가
- migration 파일 생성
- GitHub push
- 자동 배포
- 배포 완료 후 migration 자동 실행
프로세스가 아주 깔끔해졌습니다.
현재 상태는 다음과 같습니다.
- 로컬 개발 후 push만 하면 배포 완료
- DB는 내부 네트워크로만 통신
- 서버 직접 접근 불필요
- 마이그레이션 누락 위험 없음
이는 서버를 “관리”하는 방식이 아니라
로컬 개발 흐름을 클라우드로 확장한 구조에 가깝습니다.
'외주 제작 경험' 카테고리의 다른 글
| Swiper Library의 내부 디자인 영역(Transform)에서 벗어나기 (0) | 2026.02.15 |
|---|---|
| 팀원끼리 테일윈드 배치가 다 다를때 지저분함을 통일시키는 법 (1) | 2026.02.01 |
| 배포 장애 대응: JWT 환경변수 강제화 및 Swagger 서버 분리 (7) | 2026.01.24 |
| Vite만 쓰다 Next App Router 쓰면 반드시 헷갈리는 것들 (1) | 2026.01.21 |
| 어드민 로그인 인증 로직을 이해하기 (0) | 2026.01.07 |