Docker 업데이트 전 호환성 체크리스트

이런 상황일 때

컨테이너 이미지에 새 판이 나왔습니다. 태그를 올리면 되는 것 같은데, 지난번에 그러다 설정이 통째로 안 먹어 한참 고생했습니다. 무엇을 미리 봐야 그런 일이 없을지 모르겠습니다.

한 줄 결론

엔진 판보다 이미지가 무엇을 바꿨는지가 훨씬 중요합니다. 특히 볼륨 경로와 환경 변수 이름 — 실제 사고의 대부분이 여기서 납니다.

핵심 개념

태그는 약속의 세기가 다르다

1.2.3 은 그 판을 가리키고 바뀌지 않습니다. 1.2 는 그 줄의 최신을 따라 움직입니다. latest 는 아무것도 약속하지 않습니다 — 만드는 쪽이 붙이기 나름입니다.

볼륨 경로가 바뀌면 데이터가 사라진 것처럼 보인다

이미지가 데이터를 두는 위치를 바꾸면, 내 볼륨은 옛 경로에 붙어 있어 빈 상태로 시작합니다. 데이터는 그대로 있는데 안 보이는 상태입니다.

환경 변수 이름이 바뀌면 조용히 기본값으로 돈다

모르는 변수는 대개 무시됩니다. 오류도 안 나고 프로그램은 잘 뜹니다. 그런데 내가 설정한 값은 적용되지 않은 상태입니다. 가장 알아채기 어려운 종류입니다.

업데이트 전 백업은 셋이다

compose 파일, 환경 변수 파일(.env), 그리고 볼륨 — 이 셋이면 어제 상태로 돌아갈 수 있습니다. 무엇을 왜 백업하는지의 일반 원칙은 백업 글에 있고, 여기서는 Docker 에서의 그 셋을 아래 명령으로 구체화합니다. (2026-08-07 보강 — 확장 기획 13번을 이 글에 흡수)

엔진 판은 생각보다 덜 중요하다

Docker Engine 이나 Compose 판 때문에 깨지는 일은 드뭅니다. 다만 compose 파일 문법에 새 항목을 쓰려면 그만한 판이 필요합니다.

이런 분에게 해당됩니다

• compose 로 여러 컨테이너를 엮어 쓰는 홈서버 사용자
• NAS 의 컨테이너 관리 화면에서 이미지를 올리는 분
• latest 태그를 쓰고 있는 분

확인해야 할 항목

• 지금 쓰는 태그가 무엇을 가리키는가
• 이미지 문서에서 볼륨 경로가 바뀌었는가
• 환경 변수 이름이 바뀌거나 없어졌는가
• compose 파일이 지금 Compose 판에서 유효한가
• 지금 돌고 있는 이미지의 실제 판을 적어 두었는가

잘못 이해하기 쉬운 부분

안전한 행동 순서

1. 지금 돌고 있는 이미지의 실제 판을 기록합니다. 되돌릴 지점입니다.
2. 이미지 문서에서 볼륨 경로와 환경 변수 목록을 확인합니다.
3. 내 compose 파일의 항목 이름과 하나씩 대조합니다.
4. compose 파일이 문법상 유효한지 검사합니다.
5. 올린 뒤 내가 설정한 값이 실제로 먹었는지 확인합니다 — 뜨는 것만으로는 부족합니다.
6. 태그를 latest 로 쓰고 있었다면 이참에 번호로 바꿔 둡니다.

compose 파일이 유효한지 검사

docker compose config --quiet

아무것도 출력되지 않으면 이상 없다는 뜻입니다 · 확인: 2026-08-05 · wp3 VM (Debian, Docker Compose v2)

지금 돌고 있는 이미지의 실제 판 기록

docker compose images
docker image inspect --format '{{index .RepoDigests 0}}' <이미지>

latest 를 쓰고 있어도 여기 찍힌 값으로 정확히 되돌아갈 수 있습니다 · 확인: 2026-08-05 · wp3 VM (Debian, Docker Compose v2)

업데이트 전 — 볼륨 백업

docker run --rm -v <볼륨이름>:/from:ro -v "$PWD":/to alpine tar czf /to/backup.tgz -C /from .
tar tzf backup.tgz

볼륨을 읽기 전용으로 물려 백업만 만듭니다. 데이터베이스는 그 DB 의 덤프 도구가 먼저입니다. compose 파일과 .env 는 평범한 파일 복사면 됩니다 (2026-08-07 보강) · 확인: 2026-08-07 · wp3 VM (Debian, Docker Engine 29.7.1)

확인 체크리스트

• compose 파일·환경 변수 파일·볼륨을 백업했다
• 지금 이미지의 실제 판을 기록했다
• 볼륨 경로 변경 여부를 확인했다
• 환경 변수 이름을 대조했다
• compose 파일 문법을 검사했다
• 올린 뒤 설정 값이 실제로 먹었는지 확인했다

관련 도구와 버전 페이지

• 컨테이너 최신 버전 정리
  Docker Compose·Portainer·containerd 의 현재 판을 정리해 두었습니다. Docker Engine 과 Docker Desktop 은 이 사이트의 추적 대상이 아닙니다 — 공식 릴리스 노트를 보셔야 합니다.

자주 묻는 것

태그를 번호로 고정하면 업데이트를 놓치지 않나요?

놓치는 게 아니라 내가 정할 수 있게 됩니다. 새 판이 나왔는지는 따로 알림으로 받고, 올릴 때 번호를 바꾸면 됩니다.

볼륨 경로가 바뀐 걸 나중에 알았습니다. 데이터는요?

대개 그대로 있습니다. 옛 경로에 있는 데이터를 새 경로로 옮기거나, 볼륨을 새 경로에 다시 물리면 됩니다. 새로 만들어진 빈 데이터를 지우기 전에 옛 볼륨이 어디 있는지부터 확인하세요.

환경 변수가 먹었는지 어떻게 확인하나요?

프로그램의 설정 화면이나 상태 페이지에서 그 값이 실제로 반영됐는지 보는 것이 가장 확실합니다. 로그 첫머리에 설정을 찍어 주는 프로그램도 많습니다.