[Docker] Docker 환경에서 yarn 설치 시 인증서 오류 해결

문제 상황

사내망 환경에서 오픈소스 프로젝트를 Docker로 빌드하는 도중, 다음과 같은 명령어를 Dockerfile에 사용하게 되었습니다.

RUN yarn global add turbo

또는

RUN yarn install

하지만 빌드 중 다음과 같은 에러가 발생했습니다:

error Error: unable to verify the first certificate

또는

SSL Error: UNABLE_TO_VERIFY_LEAF_SIGNATURE

이는 외부 레지스트리(https://registry.yarnpkg.com)에 접근할 때 TLS 인증서를 검증하지 못해 발생하는 오류입니다.

원인 분석

이 문제는 일반적으로 다음과 같은 내부망 환경에서 발생합니다.

• 사내망에서 외부 인증서를 완전히 신뢰하지 않음
• 외부 사이트의 인증서 체인(leaf → intermediate → root)을 검증할 수 없음
• 사내 프록시를 통해 트래픽이 전달되며 인증서가 중간에 변경됨
• Docker 컨테이너 내에서는 호스트 시스템의 인증서 체계를 공유하지 않음

해결 방법

1. TLS 인증서 검증 비활성화 (개발용 한정)

Dockerfile 내에 환경 변수를 추가하여 SSL 인증서 검증을 무시하도록 설정합니다.

ENV NODE_TLS_REJECT_UNAUTHORIZED=0
RUN yarn install

또는 yarn 설정 자체를 변경할 수도 있습니다.

RUN yarn config set "strict-ssl" false
RUN yarn install

주의: 이 방법은 보안상 매우 위험하므로 실제 운영 환경에서는 사용을 피해야 하며, 내부 테스트용으로만 사용해야 합니다.

2. 프록시 환경 변수 설정

사내에서 사용하는 HTTP(S) 프록시 서버가 있다면 아래와 같이 환경 변수를 설정합니다.

ENV http_proxy=http://proxy.company.com:8080
ENV https_proxy=http://proxy.company.com:8080
RUN yarn install

3. 사설 인증서를 Docker 컨테이너에 직접 등록

사내에서 사용하는 루트 인증서 파일(.crt 또는 .pem)을 Docker 이미지에 복사한 후 시스템에 등록하는 방식입니다.

COPY company-cert.pem /usr/local/share/ca-certificates/company-cert.crt
RUN update-ca-certificates
RUN yarn install

이 방법은 인증서 검증을 유지하면서도 보안 설정을 지킬 수 있어 가장 안정적입니다.

4. yarn 대신 npm 사용

특정 패키지 설치가 목적이라면 yarn 대신 npm을 사용하는 것도 고려할 수 있습니다.

RUN npm install -g turbo

상황에 따라 npm은 yarn보다 인증서 오류에 덜 민감하게 작동하기도 합니다.

적용 예시 요약

# 방법 1. 임시 개발용
ENV NODE_TLS_REJECT_UNAUTHORIZED=0
RUN yarn config set "strict-ssl" false
RUN yarn install

# 방법 2. 프록시 설정
# ENV http_proxy=http://proxy.company.com:8080
# ENV https_proxy=http://proxy.company.com:8080
# RUN yarn install

# 방법 3. 인증서 직접 등록
COPY company-cert.pem /usr/local/share/ca-certificates/company-cert.crt
RUN update-ca-certificates
RUN yarn install

마무리

사내 네트워크에서는 외부 인증서를 완전히 신뢰하지 않는 경우가 많아, yarn install 같은 기본적인 명령어도 인증서 오류로 실패할 수 있습니다. 이럴 때는 임시적인 우회 방법보다는 인증서를 등록하거나 프록시 설정을 적용하는 방식으로 문제를 해결하는 것이 더 바람직합니다.