왓치타워로 도커 컨테이너 자동 업데이트하는 법｜설정 4단계로 안전하게 적용하기
이미지 새 버전 나올 때마다 손으로 재배포하지 마세요
- 왓치타워는 도커 소켓을 감시해 새 이미지가 올라오면 컨테이너를 자동으로 교체해주는 도구입니다.
- 기본 폴링 주기는 24시간(86400초)이며, 환경변수로 원하는 주기로 바꿀 수 있습니다.
- 라벨을 지정하면 원하는 컨테이너만 골라서 자동 업데이트할 수 있습니다.
- 운영 서비스에는 알림만 받는 모니터 전용 모드로 시작하는 게 안전합니다.
- 공식 문서도 상업·운영 환경보다는 홈랩·개인 서버 용도를 권장합니다.
홈서버에 컨테이너를 10개쯤 돌리다 보면, 매번 이미지 업데이트를 확인하고 손으로 재배포하는 일이 슬슬 귀찮아집니다.
새 버전이 나왔는지 매주 확인하고, docker pull부터 docker stop, docker run까지 반복하는 건 시간 낭비입니다.
왓치타워는 이 과정을 통째로 자동화해줍니다. 도커 소켓을 감시하다가 새 이미지가 레지스트리에 올라오면 알아서 컨테이너를 내리고 새로 띄웁니다.
이 글에서는 왓치타워 설치부터 업데이트 주기 설정, 특정 컨테이너만 골라 업데이트하는 법까지 순서대로 정리합니다.
왓치타워란? 도커 컨테이너 자동 업데이트 원리
왓치타워는 컨테이너 형태로 배포되는 오픈소스 도구입니다. 자기 자신도 컨테이너로 실행되며, 다른 컨테이너들을 감시하는 역할을 합니다.
동작 방식은 단순합니다. 정해진 주기마다 레지스트리에 새 이미지가 있는지 확인하고, 있으면 기존 컨테이너를 우아하게 종료한 뒤 같은 설정으로 새 컨테이너를 다시 만듭니다.
이 과정에서 컨테이너를 실행할 때 썼던 포트·볼륨·환경변수 등 옵션은 그대로 유지됩니다. 사용자가 따로 재설정할 필요가 없습니다.
왓치타워가 컨테이너 상태를 감시하려면
/var/run/docker.sock을 마운트해야 합니다. 이건 왓치타워에게 도커 데몬을 제어할 권한을 넘겨주는 것과 같습니다. 그만큼 신뢰할 수 있는 환경에서만 쓰는 게 원칙입니다.공식 GitHub 저장소에서도 왓치타워는 홈랩·미디어센터·개인 개발 환경을 위한 도구라고 명시합니다. 상업적 운영 서비스에는 권장하지 않습니다.
운영 환경에서 무중단 배포가 필요하다면 쿠버네티스 같은 오케스트레이션 도구를 검토하는 게 맞습니다. 왓치타워는 어디까지나 “간단하게 최신 상태 유지”가 목적입니다.
왓치타워 설치하고 실행하는 법
왓치타워 설치는 이미지 하나만 받으면 끝납니다. 별도의 바이너리 설치나 복잡한 의존성 설정이 필요 없습니다.
가장 간단한 실행 방법은 docker run -d --name watchtower -v /var/run/docker.sock:/var/run/docker.sock containrrr/watchtower 한 줄입니다. 이 명령만으로 실행 중인 모든 컨테이너를 감시하기 시작합니다.
docker-compose를 쓴다면 image: containrrr/watchtower와 소켓 볼륨 한 줄만 추가하면 됩니다. 다른 서비스들과 함께 한 파일에서 관리할 수 있어 더 편리합니다.
주의할 점은 인자 없이 실행하면 호스트의 모든 컨테이너를 감시 대상으로 삼는다는 것입니다. 특정 컨테이너만 감시하려면 명령어 뒤에 컨테이너 이름을 나열하면 됩니다.
예를 들어 containrrr/watchtower nginx redis처럼 실행하면 nginx와 redis 컨테이너만 자동 업데이트 대상이 됩니다. 나머지 컨테이너는 그대로 유지됩니다.
처음 도입한다면
--run-once 옵션으로 한 번만 실행해보세요. 실제로 업데이트가 어떻게 일어나는지 로그로 확인한 뒤, 문제없으면 상시 실행으로 전환하는 게 안전합니다.폴링 주기·스케줄 설정하기
기본 설정으로 두면 왓치타워는 24시간(86400초)마다 한 번씩 새 이미지가 있는지 확인합니다. 이 주기는 상황에 맞게 조절할 수 있습니다.
WATCHTOWER_POLL_INTERVAL 환경변수에 초 단위 숫자를 넣으면 됩니다. 예를 들어 3600을 넣으면 1시간마다, 300을 넣으면 5분마다 확인합니다.
특정 시간대에만 업데이트하고 싶다면 WATCHTOWER_SCHEDULE로 cron 표현식을 쓸 수 있습니다. 새벽 4시처럼 트래픽이 적은 시간을 지정하는 경우가 많습니다.
주의할 점은 --interval과 --schedule을 동시에 쓸 수 없다는 것입니다. 둘 중 하나만 선택해야 합니다.
운영 서버라면 폴링 주기를 너무 짧게 잡지 않는 걸 권장합니다. 레지스트리에 과도한 요청을 보내면 API 호출 제한에 걸릴 수 있습니다.
특정 컨테이너만 업데이트하기 – 라벨과 이름 필터
모든 컨테이너를 무조건 자동 업데이트하는 건 위험할 수 있습니다. 데이터베이스처럼 신중하게 다뤄야 할 컨테이너는 제외하고 싶을 때가 많습니다.
가장 확실한 방법은 라벨 필터링입니다. WATCHTOWER_LABEL_ENABLE=true로 왓치타워를 실행하면, com.centurylinklabs.watchtower.enable=true 라벨이 붙은 컨테이너만 업데이트 대상이 됩니다.
즉 업데이트를 원하는 컨테이너에만 라벨을 붙이고, 나머지는 그대로 두면 됩니다. 새 컨테이너를 추가할 때도 라벨만 붙이면 자동으로 감시 목록에 들어갑니다.
라벨 대신 이름으로 직접 지정하는 방법도 있습니다. containrrr/watchtower web app database처럼 컨테이너 이름을 나열하면 딱 그 컨테이너들만 업데이트합니다.
두 방식의 차이는 관리 방향입니다. 라벨 방식은 컨테이너를 새로 만들 때마다 신경 써야 하지만 유연하고, 이름 방식은 왓치타워 설정 한 곳만 고치면 되지만 컨테이너가 늘어날 때마다 손이 갑니다.
운영 데이터베이스, 스토리지 관련 컨테이너에는 반대로
com.centurylinklabs.watchtower.enable=false 라벨을 명시적으로 붙여두세요. 실수로 감시 대상에 포함되는 걸 원천적으로 막을 수 있습니다.왓치타워 사용할 때 자주 하는 실수와 주의점
왓치타워는 설정이 간단한 만큼, 반대로 아무 설정 없이 켜뒀다가 예상치 못한 문제를 겪는 경우가 많습니다.
첫 번째는 전체 감시 모드로 방치하는 것입니다. 인자 없이 실행하면 나중에 추가한 컨테이너까지 전부 자동 업데이트 대상이 됩니다. 라벨이나 이름 필터를 꼭 설정해야 합니다.
두 번째는 이미지 태그를 latest로만 쓰는 경우입니다. 특정 버전을 명시하지 않으면 예기치 않은 메이저 업데이트가 그대로 적용돼 서비스가 깨질 수 있습니다.
세 번째는 알림 설정을 빼먹는 것입니다. 왓치타워가 언제 무엇을 업데이트했는지 모르면, 서비스에 문제가 생겼을 때 원인 파악이 늦어집니다. Slack이나 이메일 알림 연동을 권장합니다.
네 번째는 오래된 이미지를 정리하지 않는 것입니다. WATCHTOWER_CLEANUP=true를 설정하지 않으면 업데이트할 때마다 이전 이미지가 디스크에 계속 쌓입니다.
왓치타워를 처음 도입할 때는 “업데이트”보다 “모니터링”부터 시작하는 걸 추천합니다.
WATCHTOWER_MONITOR_ONLY=true로 켜두면 새 이미지가 있을 때 알림만 오고 실제 교체는 하지 않습니다. 며칠 지켜본 뒤 자동 업데이트로 전환하면 훨씬 안전합니다.도커 소켓을 마운트한다는 건 왓치타워에 호스트의 모든 컨테이너를 제어할 권한을 주는 것과 같습니다. 신뢰할 수 없는 이미지를 왓치타워로 쓰지 않도록 공식 이미지인지 반드시 확인하세요.
자주 묻는 질문
공식 문서는 홈랩·개인 서버용을 권장하며 상업 운영 환경에는 권장하지 않습니다. 운영 서비스라면 라벨 필터와 알림을 꼼꼼히 설정하거나 쿠버네티스 같은 도구를 검토하세요.
네, 별도로 제외하지 않으면 왓치타워 컨테이너 자신도 감시 대상에 포함되어 새 버전이 나오면 스스로 교체됩니다.
기본 동작은 컨테이너를 정지 후 재시작하는 방식이라 짧은 다운타임이 발생합니다. 무중단이 필요하면 rolling restart 옵션이나 별도 로드밸런서 구성을 검토해야 합니다.
가능합니다. 왓치타워는 Slack, 이메일, Discord 등 다양한 알림 서비스를 지원하며 환경변수로 웹훅 주소나 SMTP 정보를 설정하면 됩니다.
네, containrrr Docker Hub에서 armhf 태그가 붙은 이미지를 제공하므로 라즈베리파이 같은 ARM 환경에서도 문제없이 실행됩니다.
📖 핵심 용어 미니 사전
본문에 나온 용어가 낯설다면 아래에서 먼저 확인해보세요.
일정한 주기로 상태를 확인하는 방식입니다. 왓치타워는 폴링으로 새 이미지를 확인합니다.
도커 데몬과 통신하는 통로로, 컨테이너를 제어할 수 있는 권한을 담고 있습니다.
실제 업데이트는 하지 않고 새 이미지가 있다는 알림만 보내는 설정입니다.
특정 시간·주기를 문자열로 지정하는 스케줄링 표기법입니다.
🔗 공식 자료
📖 출처
Watchtower 공식 문서(containrrr.dev) – 개요, 사용법 가이드, 전체 옵션 레퍼런스와 공식 GitHub 저장소를 참고했습니다.
왓치타워는 도커 소켓만 마운트하면 새 이미지가 나올 때마다 컨테이너를 자동으로 교체해줍니다. 라벨 필터와 모니터 전용 모드로 시작하면 훨씬 안전하게 자동 업데이트를 도입할 수 있습니다.
