[npm] 폐쇄망 환경에서 배포시 의존성 문제 해결하기

목차

1. 개요
2. npm과 yarn
3. yarn을 사용하는 이유
4. 배포

---

개요

외부 인터넷을 사용할 수 없는 폐쇄망 환경(또는 네트워크 환경이 느린 환경)에서 빌드 또는 실행에 필요한 의존성을 받아올 수 없는 상황에서 의존성을 사용할 수 있게 하기.

 

node.js 기반의 react 개발을 잘 모르는 상황에서 프론트 개발자에게 react프로젝트를 인수인계 받았고, 관리하고 있는 서버에 배포해야하는 상황. Docker를 이용해서 배포 하려고 하니 npm을 통해 빌드시 의존성을 찾을 수 없다는 에러가 발생함.

---

npm과 yarn

npm과 yarn은 자바스크립트 패키지 매니저입니다.

패키지는 npm에 등록된 노드 모듈로써, 다양한 자바스크립트 프로그램으로 구성되어 흔히 의존성이라고 합니다.

 

npm은 이러한 의존성들의 다운로드, 의존성 관리, 제거 등 복잡한 일들을 수행해주어 편리한 개발을 도와주는 도구라 볼수 있습니다.

 

yarn을 이러한 npm에서 더 개선된 버전으로 똑같이 의존성 관리 등의 역할을 하는 패키지 매니저입니다.

npm과 차이라면 병렬 다운로드 및 캐싱으로 인한 빠른 속도와 yarn.lock이나 package.json파일에 등록된 지정된 파일만 설치되도록 하는 보안성 그리고 폐쇄망과 느린 네트워크 환경에서 사용할 수 있는 오프라인 기능 지원을 제공한다는 차이가 있습니다.

yarn을 사용하는 이유

앞서 npm과 yarn의 차이에서 오프라인 기능 지원이라는 차이점으로 인해 폐쇄망 환경에서 의존성 관리를 하기 위해선 yarn을 사용합니다.

 

폐쇄망 환경은 외부 인터넷 접근이 불가능하므로, 패키지 설치를 위해서는 사내 저장소를 사용하거나 미리 다운로드된 패키지가 필요합니다.

 

yarn의 오프라인 기능인 오프라인 미러(Offline Mirror)기능은 이 문제를 해결해줍니다.

---

.yarnc

루트 경로에 .yarnc파일을 생성합니다.

해당 내용들은 yarn에게 외부 레지스트리에 접근할 수 없을 때 사용할 로컬 패키지 저장소를 지정해줍니다.

//.yarnc
yarn-offline-mirror "./npm_packages"
yarn-offline-mirror-pruning true

yarn-offline-mirror

yarn이 패키지를 다운받을 때, 패키지의 압축 파일(.tgz파일)을 지정된 로컬 디렉터리(./npm_packages)에도 복사하여 저장하도록 지시합니다.

 

yarn-offline-mirror 동작 원리

1. 외부망에서 작업
   • 인터넷이 되는 환경에서 yarn install 수행시, 필요한 .tgz파일이 ./npm_packages폴더에 쌓입니다.
2. 폐쇄망으로 이동
   • ./npm_packages폴더를 프로젝트 코드와 함께 폐쇄망 서버로 옮깁니다.
3. 폐쇄망에서 설치
   • 폐쇄망에서 yarn install 수행시, yarn은 먼저 ./npm_packages폴더를 확인하고, 파일이 존재한다면 외부망 접근 없이 로컬 파일만 사용하여 설치를 완료합니다.

yarn-offline-mirror-pruning

yarn-offline-mirror-pruning true 옵션 사용시, 현재 package.json과 yarn.lock에 더 이상 필요하지 않은 패키지(.tgz파일)를 자동으로 삭제(pruning)하도록 지시합니다.

 

yarn-offline-mirror는 지정한 디렉터리(./npm_packages)가 시간이 지남에 따라 사용하지 않는 구형 패키지로 비대해지는 것을 방지하여 디스크 공간을 절약하고 관리를 효율적으로 하기 위해 사용합니다.

---

yarn install --offline --frozen-lockfile

폐쇄망 환경에서 프로젝트의 의존성을 일관성 있고 안전하게 설치하기 위해 사용되는 명령어입니다.

 

yarn install

package.json파일을 기반으로 의존성 패키지를 설치합니다.

--offline

오프라인으로 패키지 설치하도록 하는 옵션입니다.

외부 네트워크 접속을 시도하지 않고 로컬 캐시 또는 오프라인 미러(.yarn 설정의 ./npm_packages)에 있는 패키지만을 사용하여 설치를 진행합니다.

--frozeon-lockifle

lockfile을 구정하는 옵션입니다.

yarn.lock파일의 내용을 절대 변경하지 않도록 강제합니다. 설치 시 패키지 버전이나 구조가 yarn.lock과 일치하지 않으면 설치를 실패시키고 에러를 발생시킵니다.

---

폐쇄망에 배포하기

react프로젝트의 패키지 매니저를 npm에서 yarn으로 변경해서 리눅스 서버에 docker를 이용해 배포하는 과정입니다.

(1) yarn 패키지 설치(외부망)

$ npm install yarn

(2) .yarnc 파일 생성(외부망)

react프로젝트의 루트 디렉터리에 .yarnc 파일을 생성 후 아래의 내용 작성

yarn-offline-mirror "./npm_packages"
yarn-offline-mirror-pruning true

(3) 기존 파일 삭제 및 캐시 삭제(외부망)

기존에 존재하던 node_modules와 yarn.lock파일 삭제

루트 디렉터리의 node_modules와 yarn.lock

캐시 삭제

$ yarn cache clean

(4) 패키지 다운로드(외부망)

$ yarn install

package-lock.json, yarn.lock 등 파일이 생성되고 npm_packages에 필요한 의존성이 추가됩니다.

(5) Dockerfile 작성(외부망)

오프라인 환경에서 사용해야할 패키지와 필요 파일들을 docker 이미지화 할때 이동시킬 수 있도록 dockerfile을 작성합니다.

FROM 10.10.5.66:444/library/node:22 as builder

WORKDIR /app

#폐쇄망에서 사용할 의존성 패키지 파일들 복사
COPY package.json yarn.lock .yarnrc ./
COPY npm_packages ./npm_packages

# package.json 및 package-lock.json 파일에 명시된 의존성 패키지들을 설치
RUN yarn install --offline --frozen-lockfile

# 호스트 머신의 현재 디렉토리 파일들을 컨테이너 내부로 전부 복사
COPY . .

RUN yarn build

FROM 10.10.5.66:444/library/nginx:1.29

COPY --from=builder /app/dist /usr/share/nginx/html

RUN chmod -R 777 /var/cache/nginx && \
    chmod -R 777 /var/log/nginx && \
    chmod -R 777 /var/run

RUN rm /etc/nginx/conf.d/default.conf

COPY nginx/nginx.conf /etc/nginx/conf.d

EXPOSE 21000

CMD ["nginx", "-g", "daemon off;"]

오프라인 의존성 관리시 필요한 파일인 package.json, yarn.lock, .yarnc, npm_packes를 복사하는 명령어를 작성합니다.

(6) 폐쇄망으로 소스코드 이동(외부망 > 폐쇄망)

테스트를 환경에서 하다보니 개인 vm으로 이동시킵니다. (실제 작업에서는 gitlab ci 를 통해 소스코드 이동이 발생했습니다.)

명령어 : scp [복사 대상 파일 ] [서버 계정]@[서버 ip]:[복사 위치]

scp 명령어로 파일 이동

(7) 패키지 다운로드(폐쇄망)

...

#yarn을 이용한 다운로드
RUN yarn install --offline --frozen-lockfile

...

폐쇄망에서 yarn install --offline --frozoen-lockfile을 실행시킵니다.

dockerfile에서 수행된 yarn install

(8) 배포

위의 과정을 거치게 되어 생성된 도커 이미지(mobile_framework_react:0.2)를 실행시킵니다.

docker run -d --name mobile_framework_react_test2 -p 21000:21000 mobile_framework_react:0.2

 

생성된 도커 컨테이너

배포된 url로 접근

---

참조

https://seogeurim.tistory.com/12

npm? yarn? 그 차이가 뭐길래...