대상 사용자: 프로그래머. Dockerfile의 잘못된 명령과 재현하기 어려운 이미지 버전을 빌드 전에 찾고 싶은 개발자를 위한 안내입니다. Hadolint는 Dockerfile을 정적 검사하는 도구입니다. 컨테이너를 빌드하거나 실행하지 않습니다. 공식 사용 설명의 명령과 규칙을 기준으로 작성했습니다.
설치와 배포본 안내
- 공식 2.15.1 릴리스에서 Windows x64용
hadolint-windows-x86_64.exe와checksums.sha256을 받습니다. 다른 운영체제라면 해당 릴리스의 플랫폼 파일을 고릅니다. - PowerShell에서
Get-FileHash .\hadolint-windows-x86_64.exe -Algorithm SHA256으로 내려받은 파일의 해시를 구하고checksums.sha256의 같은 파일 이름 옆 값과 비교합니다. 2.15.1 Windows x64 배포본의 검증된 SHA-256은01d927294962b5387f9ead4f18679158452be4f17c765ad0bdffe5264b9c7b0a입니다. 값이 다르면 실행하지 말고 공식 릴리스에서 다시 받습니다. ./hadolint-windows-x86_64.exe --version으로Haskell Dockerfile Linter 2.15.1을 확인합니다. 편의상 실행 파일 이름을 바꾸거나 PATH에 추가할 수 있으나, 처음에는 내려받은 폴더에서 직접 실행하는 편이 쉽습니다.
이 자료실 ZIP에는 Hadolint 설치 파일이 포함되지 않습니다. Hadolint는 GPL-3.0 라이선스와 서드파티 의존성 고지가 있는 공식 프로그램입니다. 이 게시물에는 실행 파일과 대응 소스 전체를 재배포하지 않고 공식 릴리스 링크를 제공합니다. 첨부 ZIP은 자체 작성한 한국어 설명서와 실습 Dockerfile만 담습니다.
첫 검사
첨부 ZIP을 압축 해제하고 PowerShell에서 다음을 실행합니다. 실행 파일 경로는 실제 다운로드 위치로 바꾸세요.
& 'C:\Tools\hadolint-windows-x86_64.exe' .\practice\Dockerfile.bad
실습 파일의 FROM alpine은 버전을 고정하지 않아 DL3006 경고, WORKDIR app은 절대 경로가 아니어서 DL3000 오류가 납니다. 검사 결과의 앞부분은 Dockerfile.bad:1 DL3006 warning, Dockerfile.bad:2 DL3000 error 형태입니다. 종료 코드가 0이 아니면 CI에서 검사 실패로 다룰 수 있습니다. 경고를 숨기기보다 문제를 고치는 편이 실습 목적에 맞습니다.
& 'C:\Tools\hadolint-windows-x86_64.exe' .\practice\Dockerfile.good
수정본은 FROM alpine:3.20, WORKDIR /app을 사용하며 이 예제에서는 출력 없이 종료 코드 0으로 끝납니다. 이미지 태그만으로 공급망 재현성이 완전히 보장되는 것은 아닙니다. 엄격한 배포 정책이 필요하면 팀의 이미지 digest 고정 기준도 따르세요. 실제 프로젝트에서는 Dockerfile을 실습 파일 대신 전달합니다. 공식 규칙 목록에서 다른 진단 코드의 뜻도 찾을 수 있습니다.
문제 해결
- 명령을 찾을 수 없음: 다운로드 위치를 확인하고 PowerShell에서
& '전체\경로\hadolint-windows-x86_64.exe' .\Dockerfile처럼 실행합니다. 현재 폴더의 파일은./또는.\를 붙입니다. - 해시가 다름: 파일 이름과 릴리스 버전이 모두 2.15.1인지 확인하고, 불일치 파일은 실행하지 않습니다.
- DL3006이 계속 표시됨:
FROM의 이미지에 명시적 태그가 있는지 확인합니다.latest사용은 별도 DL3007 경고가 생길 수 있습니다. - DL3000이 계속 표시됨:
WORKDIR app대신/app같은 절대 경로를 사용합니다. - 예상과 다른 규칙: 도구 버전과 검사한 파일 경로를 먼저 확인하고, 공식 규칙 문서에서 진단 코드를 찾습니다. 이 실습은 Docker 이미지 빌드 성공이나 앱 동작을 시험한 것은 아닙니다.
이 안내는 공식 Windows 실행 파일을 로컬에서 실행하여 두 오류와 수정본의 검사 결과를 확인한 기록을 바탕으로 작성했습니다. 첨부 ZIP에는 실행 파일이 없습니다.