사내에서 사용하는 소프트웨어들은 보안팀을 통해 버전 관리가 되고 있고,
이번에 도커도 29 버전으로 업데이트가 진행되었습니다.
제가 진행 중인 프로젝트에서는 DB 등 외부 자원을 포함한 테스트를 할 때 Testcontainers(1.21.0 버전) 를 활용하고 있습니다.
그런데 도커를 업데이트한 이후, 로컬에서 테스트 코드를 실행했을 때 아래와 같은 에러 메시지가 출력되며 테스트가 동작하지 않았습니다.
Caused by: java.lang.IllegalStateException: Could not find a valid Docker environment.
Please see logs and check configuration
...
Could not find a valid Docker environment. Please see logs and check configuration
처음에는 AI에게 질문해보니 “도커 소켓 파일 이슈”일 가능성이 있다며 docker.sock 경로를 확인하라고 알려줬고,
팀원들 역시 업데이트 과정에서 소켓 파일 문제가 생긴 게 아닌지 의아해하고 있었습니다.
ls -l /var/run/docker.sock
lrwxr-xr-x 1 root daemon 37 11 25 17:27 /var/run/docker.sock -> /Users/***/.docker/run/docker.sock확인해보니 /var/run/docker.sock는 여전히 정상적으로 심볼릭 링크가 걸려 있었고,
소켓 문제는 아니라는 확신이 들었습니다.
원인 파악을 위한 디버깅
여러 작은 부분부터 하나씩 확인해보았지만 뚜렷한 원인을 찾지는 못했고,
결국 Testcontainers 내부를 직접 디버깅해보기로 했습니다.
제 컴퓨터의 도커 버전을 확인한 결과는 다음과 같았습니다.
> docker version
Client:
Version: 29.0.1
API version: 1.52
...
Server:
Version: 29.0.1
API version: 1.52 (minimum version 1.44)
...여기서 눈에 띄는 점은 Docker 서버가 최소 API 1.44 버전을 요구한다는 것이었습니다.
Testcontainers 내부 코드 분석
Testcontainers의 DockerClientProviderStrategy.java를 살펴보니,
특별히 설정된 API 버전이 없을 경우 기본값을 1.32로 사용하고 있다는 사실을 확인했습니다.
즉,
- 도커는 최소 1.44를 요구
- Testcontainers는 기본값으로 1.32를 사용
→ 이 불일치 때문에 “valid Docker environment를 찾을 수 없다”는 오류가 발생한 것입니다.
해당 이슈에 대해 기여를 할 수 있을지 확인하고자 Testcontainers GitHub 이슈를 확인해보니 이미 관련 이슈 가 제기되어있었습니다.
현재 해결책: Testcontainers 버전을 2.0.2 로 변경
https://mvnrepository.com/artifact/org.testcontainers/testcontainers/2.0.2
위 레포지토리에서 디펜더시를 받아 사용하면 됩니다.
임시 해결책: 로컬에서 Testcontainers의 API 버전을 강제 설정
수정 버전이 배포될 때까지 기다릴 수도 있지만,
개발 과정에서 테스트를 정상적으로 돌릴 수 없다는 점이 문제였습니다.
그래서 로컬에서 Testcontainers가 사용하는 도커 API 버전을 직접 1.44로 강제하는 방법을 적용했습니다.
Mac 기준입니다!
1. 아래 파일을 생성 또는 수정합니다.
vi $HOME/.docker-java.properties
2. i 눌러 편집 모드로 들어간 후 아래 내용을 입력합니다.
api.version=1.44
3. :wq 를 입력해서 저장합니다.
이 설정을 추가한 후 테스트를 다시 실행했더니 정상적으로 동작했습니다.
해당 이슈와 해결 방법을 팀원들에게 공유했고,
모두 문제없이 테스트 코드를 실행할 수 있게 되었습니다.
Testcontainers 2.0.2 버전이 릴리즈 된 이후엔 해당 버전으로 프로젝트를 업데이트 했습니다.
같은 버전의 도커를 사용하는 환경이라면
비슷한 문제를 겪을 가능성이 있으니 참고하시면 좋을 것 같습니다.