Docker를 사용하여 자동화 스크립트를 작성하거나 여러 개의 컨테이너를 순차적으로 실행하는 환경에서는 특정 컨테이너가 종료될 때까지 기다려야 하는 경우가 자주 발생합니다.
예를 들어 데이터 백업 컨테이너가 작업을 완료한 후 다음 작업을 실행하거나, 데이터베이스 마이그레이션이 끝난 뒤 애플리케이션을 시작해야 하는 상황이 있습니다.
이럴 때 사용하는 명령어가 바로 docker wait입니다.
Docker Wait는 지정한 컨테이너가 종료될 때까지 현재 터미널을 대기 상태로 유지하는 명령어입니다. 컨테이너가 종료되면 종료 코드(Exit Code)를 반환하므로 Shell Script나 CI/CD 자동화에서도 매우 자주 활용됩니다.
이번 글에서는 Docker Wait의 개념부터 기본 사용법, 종료 코드 확인 방법, 실무 활용 사례, 운영 시 주의사항까지 자세히 알아보겠습니다.
Docker Wait란 무엇인가?
Docker Wait는 특정 컨테이너가 종료될 때까지 기다리는 명령어입니다.
명령을 실행하면 컨테이너가 종료될 때까지 프롬프트가 반환되지 않습니다.
컨테이너가 종료되면 Exit Code를 출력한 후 명령이 종료됩니다.
자동화 스크립트에서는 다음 작업을 수행하기 위한 동기화(Synchronization) 용도로 많이 사용됩니다.
Docker Wait는 언제 사용하는가?
다음과 같은 상황에서 많이 사용됩니다.
- 백업 작업 완료 대기
- 데이터베이스 초기화 완료 확인
- 배치 작업 종료 확인
- CI/CD 자동화
- Shell Script 작성
- 여러 컨테이너의 순차 실행
Docker Compose와 함께 자동화 작업을 구성할 때도 활용됩니다.
Docker Wait 기본 사용법
기본 사용 방법은 다음과 같습니다.
docker wait <컨테이너명>예를 들어 backup-job 컨테이너가 종료될 때까지 기다리려면 다음과 같이 실행합니다.
docker wait backup-job컨테이너가 종료되면 다음과 같이 종료 코드가 출력됩니다.
00은 정상 종료를 의미합니다.
종료 코드(Exit Code)란?
Docker Wait는 컨테이너 종료 시 Exit Code를 반환합니다.
대표적인 종료 코드는 다음과 같습니다.
| 종료 코드 | 의미 |
|---|---|
| 0 | 정상 종료 |
| 1 | 일반 오류 |
| 125 | Docker 실행 오류 |
| 126 | 명령 실행 불가 |
| 127 | 명령을 찾을 수 없음 |
| 137 | 강제 종료(OOM, SIGKILL 등) |
| 143 | SIGTERM으로 정상 종료 |
자동화 스크립트에서는 이 값을 이용하여 다음 작업을 수행할지 결정할 수 있습니다.
여러 컨테이너 동시에 대기
여러 개의 컨테이너를 동시에 지정할 수도 있습니다.
docker wait db-init api-init모든 컨테이너가 종료될 때까지 기다린 후 각각의 종료 코드를 출력합니다.
Shell Script에서 활용하기
Docker Wait는 Shell Script와 함께 사용하는 경우가 많습니다.
docker start backup
docker wait backup
echo "백업 완료"백업 컨테이너가 종료된 후에만 다음 명령이 실행됩니다.
자동화 작업에서 매우 많이 사용하는 방식입니다.
종료 코드 변수 저장
Exit Code를 변수에 저장할 수도 있습니다.
RESULT=$(docker wait backup)이후 조건문에서 사용할 수 있습니다.
if [ "$RESULT" -eq 0 ]; then
echo "작업 성공"
else
echo "작업 실패"
fiCI/CD 파이프라인에서도 동일한 방식으로 많이 활용됩니다.
Docker Wait 실무 활용 예제
Docker Wait는 단독으로 사용하는 경우보다 Shell Script, CI/CD, 자동화 시스템과 함께 사용할 때 가장 큰 효과를 발휘합니다. 특히 하나의 작업이 완료된 후 다음 작업을 실행해야 하는 환경에서 매우 유용합니다.
데이터베이스 초기화 완료 후 애플리케이션 실행
데이터베이스 초기화 컨테이너가 완료된 후 애플리케이션을 시작해야 하는 경우입니다.
먼저 초기화 컨테이너를 실행합니다.
docker start db-init초기화가 끝날 때까지 기다립니다.
docker wait db-init종료가 확인되면 애플리케이션을 실행합니다.
docker start web-server초기화가 완료되기 전에 애플리케이션이 실행되는 문제를 예방할 수 있습니다.
백업 완료 후 압축 파일 생성
백업 컨테이너가 종료된 후 압축 작업을 수행하는 예제입니다.
docker start backup-job
docker wait backup-job
tar -czf backup.tar.gz /backup백업이 정상적으로 끝난 뒤에만 압축이 진행됩니다.
종료 코드에 따른 자동 처리
종료 코드를 이용하여 성공과 실패를 구분할 수 있습니다.
RESULT=$(docker wait migration)조건문을 사용하면 다음과 같이 처리할 수 있습니다.
if [ "$RESULT" -eq 0 ]; then
echo "Migration Success"
else
echo "Migration Failed"
fiCI/CD 환경에서 가장 많이 사용하는 방식입니다.
여러 작업 순차 실행
여러 개의 작업을 순서대로 실행할 수도 있습니다.
docker start job1
docker wait job1
docker start job2
docker wait job2
docker start job3앞선 작업이 성공적으로 종료된 후 다음 작업이 시작됩니다.
Linux 서버 문제 해결
운영 서버에서 데이터베이스 마이그레이션과 애플리케이션 배포를 자동화하고 있었습니다.
하지만 마이그레이션이 끝나기 전에 애플리케이션이 먼저 실행되어 데이터베이스 오류가 발생했습니다.
기존 스크립트는 다음과 같았습니다.
docker start migration
docker start web마이그레이션이 완료되기 전에 웹 서버가 실행되어 서비스가 정상적으로 시작되지 않았습니다.
다음과 같이 Docker Wait를 추가했습니다.
docker start migration
docker wait migration
docker start web이후에는 마이그레이션이 완전히 끝난 후 웹 서버가 실행되었고 배포 과정에서 발생하던 오류도 모두 해결되었습니다.
자동화 스크립트에서는 Docker Wait 하나만 추가해도 안정성이 크게 향상됩니다.
Docker Wait 사용 시 주의사항
Docker Wait를 사용할 때는 다음 사항을 알아두는 것이 좋습니다.
첫 번째는 실행 중인 컨테이너만 기다린다는 점입니다.
이미 종료된 컨테이너라면 즉시 종료 코드가 반환됩니다.
두 번째는 컨테이너가 종료되지 않으면 계속 대기 상태를 유지합니다.
무한 대기를 방지하려면 Shell Script에서 Timeout 기능을 함께 사용하는 것이 좋습니다.
세 번째는 종료 코드가 반드시 성공을 의미하는 것은 아닙니다.
0이 아닌 종료 코드는 대부분 오류를 의미하므로 자동화 스크립트에서는 반드시 확인해야 합니다.
Best Practice
Docker Wait를 사용할 때는 다음과 같은 방법을 추천합니다.
- 자동화 스크립트에서 종료 코드를 확인합니다.
- 작업 성공 여부를 Exit Code로 판단합니다.
- 여러 작업은 순차적으로 실행합니다.
- 장시간 작업에는 Timeout을 함께 설정합니다.
- Docker Logs와 함께 사용하여 실패 원인을 분석합니다.
- CI/CD 환경에서는 배포 검증 단계에 Docker Wait를 포함합니다.
이러한 방법을 적용하면 자동화 작업의 안정성과 신뢰성을 높일 수 있습니다.
자주 묻는 질문
Docker Wait는 실행 중인 컨테이너만 사용할 수 있나요?
네. 실행 중인 컨테이너를 대상으로 종료될 때까지 기다립니다.
종료 코드 0은 무엇을 의미하나요?
컨테이너가 정상적으로 작업을 완료했다는 의미입니다.
종료 코드가 1이면 어떻게 해야 하나요?
애플리케이션 오류일 가능성이 높습니다.
docker logs 명령으로 오류 원인을 확인하는 것이 좋습니다.
Docker Wait는 Docker Compose에서도 사용할 수 있나요?
Docker Compose 환경에서도 실행 중인 컨테이너 이름을 지정하여 사용할 수 있습니다.
마무리
Docker Wait는 컨테이너가 종료될 때까지 대기하고 종료 코드를 반환하는 간단하지만 매우 강력한 명령어입니다.
특히 Shell Script, CI/CD, 배포 자동화, 데이터베이스 초기화, 백업 작업 등 순차적인 처리가 필요한 환경에서 필수적으로 활용됩니다.
종료 코드를 기반으로 작업 성공 여부를 판단할 수 있기 때문에 안정적인 자동화 시스템을 구축하는 데 큰 도움이 됩니다.
Docker를 실무에서 운영한다면 Docker Wait를 활용하여 작업 순서를 제어하고 자동화의 안정성을 높이는 것을 추천합니다.