Coolify 업그레이드 전 점검, API 와 CI 배포가 깨지지 않게 하는 법

배포 도구는 한 번 자리를 잡으면 손대기 무서워져요. 그런데 몇 달 지나면 새 기능과 보안 수정이 쌓여서, 어느 날은 올려야 해요. 이 글은 서버 한 대에서 Coolify 를 쓰는 분들이, 버전을 올리기 전에 무엇을 확인해야 CI 배포가 멈추지 않는지 순서대로 정리해요.

혹시 이런 고민 있으신가요?

• 배포 도구를 올렸더니 어제까지 잘 되던 자동 배포가 갑자기 실패할까 봐 걱정돼요.
• 변경 내역이 길어서 내 환경에 영향이 있는 줄이 어디인지 모르겠어요.
• 문제가 생기면 어떻게 되돌릴지 정해 두지 않고 올리려니 불안해요.

이 글을 읽으면

• 변경 내역에서 내 CI 와 스크립트에 영향을 주는 줄만 골라낼 수 있어요.
• 올리기 전에 해 둘 일과 올린 뒤에 확인할 일을 표로 나눠 둘 수 있어요.
• 배포 스크립트가 도구의 API 가 바뀌어도 이유를 말하며 실패하게 만들 수 있어요.

1단계. 변경 내역에서 내 환경에 닿는 줄만 고르기

업그레이드가 깨지는 이유는 대부분 새 기능이 아니라 바뀐 동작이에요. 그래서 변경 내역을 처음부터 읽지 말고, 내가 쓰는 입구가 무엇인지부터 적어요. 입구란 도구와 내가 만나는 지점이에요.

Coolify 를 쓰는 CI 라면 입구는 보통 네 가지예요.

이 표를 들고 변경 내역을 위에서 아래로 훑으면서 해당하는 줄에만 표시해요. 저희는 4.0.0 베타에서 4.3.9 안정판으로 올리면서 이렇게 읽었고, 걸린 줄은 대략 다음과 같았어요(출처: Coolify 릴리스 노트).

• 4.2.0 부터 상태를 바꾸는 API 는 POST 만 받고, GET 으로 부르면 405 가 돌아와요.
• 4.2.0 부터 팀의 member 역할은 읽기 전용이에요.
• 4.3.0 에서 이름에 점이나 하이픈이 들어간 Compose 서비스의 라우터 이름이 바뀌었어요.
• 4.3.3 과 4.3.8 에서 네트워크가 둘 이상 붙은 서비스가 어느 네트워크로 라우팅되는지가 고쳐졌어요.

2단계. 깨질 줄을 올리기 전에 먼저 고치기

1단계에서 표시한 줄 중에는 올리기 전에 고쳐도 되는 것이 있어요. 이런 것은 업그레이드 전에 고쳐서 배포하면, 올린 뒤에 터질 문제를 미리 없앨 수 있어요.

예를 들어 배포 요청을 GET 으로 보내는 스크립트는 새 버전에서 405 를 받아요. 그런데 옛 버전은 POST 를 몰랐을 수도 있으니, 한동안 둘 다 되게 쓰면 안전해요. 저희 스크립트도 올린 뒤에 GET 쪽을 지웠어요. 아래는 그 방식을 단순하게 옮긴 예시예요.

# 4.2.0 이상은 POST 만 받아요. 옛 버전과 함께 쓰는 동안만 GET 으로 한 번 더 시도해요.code=$(curl --silent --output deploy.json --write-out '%{http_code}' --request POST \  --header "Authorization: Bearer $TOKEN" \  "$DEPLOY_URL/api/v1/deploy?uuid=$RESOURCE_UUID&force=false")if [ "$code" = 405 ]; then  code=$(curl --silent --output deploy.json --write-out '%{http_code}' --request GET \    --header "Authorization: Bearer $TOKEN" \    "$DEPLOY_URL/api/v1/deploy?uuid=$RESOURCE_UUID&force=false")fi

여기서 $DEPLOY_URL, $RESOURCE_UUID, $TOKEN 은 CI 의 비밀 변수에서 읽는 값이에요. 이 폴백은 업그레이드가 끝난 날 지워야 해요. 남겨 두면 나중에 "왜 GET 이 있지?"라는 질문만 남아요.

다음으로 토큰의 주인을 봐요. 배포에 쓰는 토큰이 member 역할 사용자의 것이면, 4.2.0 이상에서는 읽기 전용이라 상태를 바꾸는 호출이 거절돼요. 토큰을 만든 계정이 팀의 owner 나 admin 인지 올리기 전에 확인하세요.

3단계. 되돌릴 길과 백업을 먼저 만들기

도구를 올리다 실패하면 도구 자체뿐 아니라 거기 등록한 앱 설정도 문제가 돼요. 그래서 올리기 전에 다음 세 가지를 해 두세요.

1. 도구의 자체 백업을 받아요. Coolify 는 설정 화면에서 자기 데이터베이스 백업을 받을 수 있어요.
2. 올리기 직전 버전 번호를 적어 둬요. 되돌릴 때 어느 버전으로 가야 하는지 기억에 의존하지 않기 위해서예요.
3. 올릴 시간대를 정해요. 배포가 몰리지 않는 때가 안전해요.

백업은 "받아 뒀다"와 "복원해 봤다"가 달라요. 가능하면 올리기 전에 테스트용 서버에서 한 번 복원해 보세요.

여기에 4.3.0 에서 생긴 기능 하나를 같이 켜기로 했어요. 볼륨을 예약해서 S3 호환 저장소(파일을 주소로 받는 저장소)로 백업하는 기능이에요. 저희는 그때까지 백업되지 않던 파일 저장소 볼륨과 두 도구의 데이터 볼륨을 이 기능의 대상으로 잡았어요. 백업 대상은 호스트 밖에 있어야 의미가 있으니 같은 서버의 다른 디스크는 피하세요.

4단계. 올린 뒤 확인을 표로 만들어 한 번에 돌리기

올리고 나서 "되는 것 같네요"로 끝내면 안 돼요. 1단계 표의 입구를 하나씩 눌러 보는 확인을 미리 적어 두고, 올린 직후 그대로 실행해요.

세 번째 줄은 올린 뒤에 새로 켜는 설정이에요. Coolify 에는 API 를 부를 수 있는 주소를 제한하는 설정이 있고, 켜면 토큰이 새도 허용 목록 밖에서는 쓸 수 없어요. 단, 켜는 순간 CI 서버의 주소도 목록에 있어야 하니, 켜기 전에 배포 한 번이 통과하는지 같이 봐야 해요.

배포 스크립트 자체도 도구 변경에 이유를 말하며 실패하게 만들어 두면 좋아요. 저희 스크립트는 상태 코드가 기대와 다르면 코드를 그대로 요약에 적고 멈춰요.

if [ "$code" != 200 ]; then  say "배포 요청 거절: Coolify 가 HTTP $code 로 답했다"  cat deploy.json >> "$log"  exit 1fi

배포를 요청한 뒤에는 상태 조회를 10초 간격으로 최대 120번(20분) 기다리고, 끝난 다음에는 공개 주소를 10초 간격으로 18번(3분) 확인해요. 이 숫자는 이미지 빌드와 데이터베이스 변경이 함께 있어도 넉넉히 끝나는 시간으로 잡았어요. 여러분은 자기 앱의 가장 느린 배포 시간에 여유를 더해 바꾸세요.

올리기 전과 올린 뒤를 나눠 적어 두세요

자주 묻는 질문

Q1. 최신 버전이 나오면 바로 올려야 하나요?

꼭 그렇지는 않아요. 저희는 안정판만 쓰고, 후보 버전은 올리지 않았어요. 보안 수정이 들어갔다면 서두르고, 그렇지 않다면 변경 내역을 읽고 시간을 정해서 올려도 괜찮아요.

Q2. 건너뛴 버전이 많으면 하나씩 거쳐 가야 하나요?

도구마다 달라요. 중간 버전에 데이터 이전 단계가 있는 경우가 있으니, 올리려는 구간의 변경 내역에서 "이 버전을 꼭 거쳐 가라"는 문장이 있는지 찾아보세요. 있으면 그 순서를 따르세요.

Q3. 올린 뒤에 문제가 생기면 어떻게 하나요?

3단계에서 받은 백업과 적어 둔 버전으로 돌아가요. 복원을 해 본 적이 없다면, 올리는 날에는 되돌리기까지 걸리는 시간을 여유 있게 잡아 두세요.

정리

• 변경 내역은 내가 쓰는 입구를 표로 적고 해당하는 줄만 골라요.
• 요청 방식이나 토큰 권한처럼 올리기 전에 고칠 수 있는 것은 먼저 고쳐요.
• 도구 자체 백업과 직전 버전 번호를 적어 두고, 빠져 있던 백업도 이 기회에 채워요.
• 올린 뒤 확인은 입구마다 통과 기준을 적어 한 번에 돌려요.
• 배포 스크립트는 상태 코드를 숨기지 않고 말하도록 만들어요.

업그레이드의 안전은 변경 내역을 다 읽는 데서 나오지 않고, 내가 쓰는 입구에 대한 질문을 미리 적어 두는 데서 나와요.