Verdaccio Docker 서버 이전 후기 - Git 방식에서 서버 방식으로의 회귀

• 회귀의 배경

이전 사내 SCSS 모듈화 진행기에서 여러 배포 방식을 검토한 끝에 Git 방식을 선택했다고 했었는데, 결국 Verdaccio 서버 방식으로 돌아왔습니다.

당시 Git 방식을 선택했던 이유들:

간편성과 접근성
별도 서버 운영 불필요
비용 효율성
퍼블리싱 팀의 쉬운 사용
관리 포인트의 일원화

하지만 실제 운영하면서 예상치 못한 문제들이 발생했습니다.

• Git 방식의 한계점 발견

1. 버전 관리의 복잡성

// 브랜치 방식의 한계
"scss": "git+https://git-codecommit.region.amazonaws.com/scss#develop"

의미 있는 버전 번호 관리 어려움
롤백 시 커밋 해시를 직접 찾아야 하는 번거로움
팀원들이 현재 사용 중인 버전 파악 곤란
업데이트 여부의 불확실성

2. 캐싱 이슈

# 같은 브랜치명인데도 업데이트가 안 되는 경우 발생
npm install git+https://git-codecommit.region.amazonaws.com/scss#develop
# 캐시 때문에 최신 버전이 설치되지 않음

3. 권한 관리의 복잡성

각 개발자마다 CodeCommit 접근 권한 설정 필요
AWS IAM 사용자 관리 부담
임시 협력업체나 외부 개발자 접근 권한 관리 어려움
도커 컨테이너 사용 시 설정의 복잡성

• Verdaccio로의 전환 결정

결국 표준적인 npm 생태계의 장점이 Git 방식의 편의성보다 크다는 결론에 도달했습니다.

Verdaccio의 장점 재평가

표준 npm 명령어 사용

npm install @flow/scss@1.1.6
npm update @flow/scss

명확한 버전 관리
- semantic versioning 지원 → 이전 버전으로의 롤백이 자유로움
- package.json의 버전 범위 설정 가능
- 의존성 트리 명확성
안정적인 캐싱
- npm 표준 캐싱 메커니즘 활용
- 로컬 캐시로 네트워크 의존성 최소화
권한 관리 단순화
- htpasswd 기반의 간단한 인증
- 별도 AWS 계정 불필요

• Docker 기반 Verdaccio 구축

환경 일관성: 개발/스테이징/프로덕션 환경 동일
관리 편의성: 컨테이너 기반 배포 및 관리
확장성: 필요 시 로드 밸런싱과 고가용성 구성 가능
격리성: 호스트 시스템과 분리된 안전한 실행 환경

실제 구현

docker-compose.yml

services:
  verdaccio:
    image: verdaccio/verdaccio
    container_name: verdaccio
    environment:
      - VERDACCIO_PUBLIC_URL=https://my.path
    user: "1000:1000"
    volumes:
      - ./storage:/verdaccio/storage
      - ./plugins:/verdaccio/plugins
      - ./conf:/verdaccio/conf
    restart: always
 
  nginx:
    image: nginx:alpine
    container_name: nginx
    ports:
      - "80:80"
      - "443:443"
      - "4873:4873"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
    depends_on:
      - verdaccio
    restart: always

핵심 설정 포인트

볼륨 마운트로 데이터 영속성 보장

volumes:
  - ./storage:/verdaccio/storage    # 패키지 저장소
  - ./conf:/verdaccio/conf          # 설정 파일, htpasswd(계정 정보)

nginx 리버스 프록시로 HTTPS 지원

# nginx.conf 설정으로 SSL 인증서 적용
# 사내 도메인을 통한 접근 가능

환경변수로 공개 URL 설정

environment:
  - VERDACCIO_PUBLIC_URL=https://my.path

config.yaml 설정

# 스코프 패키지 설정
packages:
  '@*/*':
    access: $all
    publish: $authenticated
    unpublish: $authenticated
    # proxy: npmjs
 
# htpasswd 인증
auth:
  htpasswd:
    file: ./htpasswd
    max_users: 1000
 
# npmjs 프록시 설정은 필요하지 않고 사내 모듈만 관리하기 때문에 아래 설정은 필요하지 않음
# uplinks:
#   npmjs:
#     url: https://registry.npmjs.org/

• 이전 과정에서의 깨달음

1. 도구 선택에 대한 인사이트

“간단해 보이는 방식이 항상 최선은 아니다”

Git 방식이 초기에는 간단해 보였지만, 실제 운영에서는 npm 생태계의 표준을 벗어나면서 발생하는 여러 문제들이 있었습니다.

2. 팀 협업 관점에서의 고려사항

“개발자 친화적 != 운영 친화적”

Git 방식은 개발자에게는 친숙했지만, 실제 서비스 운영 관점에서는 다음과 같은 문제가 있었습니다:

의존성 추적의 어려움
빌드 재현성 문제
패키지 메타데이터 관리 한계

3. 다양한 환경에 대한 고려

“SaaS 환경에도, 온프레미스도 고려하라!”

저희 회사는 SaaS 환경도 사용하고, 내부망(=온프레미스 환경, 엔터 환경)에 대한 고려도 필요했습니다. 엔터 환경만 고려한다면, 혹은 클라우드 환경만 고려했다면 좀 더 쉬웠겠지만 둘 다 고려해야 했고 둘 모두 커버하기 위해 사설 NPM 서버와 doker 이미지 빌드 서버 쪽(맥에서 이미지 빌드 시 Linux에서 돌릴 때 OS 호환 이슈로 빌드 서버가 필요해졌습니다. 빌드가 서버가 필요한 이유는 배포 방식 비교참고 바랍니다.)으로 가닥이 잡혔습니다.

• 현재 운영 상황

설치 및 사용 방법

# 스코프 설정 (권장)
npm config set @flow:registry https://my.path
 
# 패키지 설치
npm install @flow/scss
 
# 버전 업데이트
npm update @flow/scss

실제 package.json

{
  "dependencies": {
    "@flow/scss": "^1.1.6"
  }
}

SCSS 사용 방법 (변경사항 없음)

// 기존
@use "../abstract/abstract" as *;
// 변경 후
@use "@flow/scss/abstract/abstract" as *;

• 성과와 개선사항

1. 버전 관리 개선

이전 (Git 방식)	현재 (Verdaccio)
`git+https://...#1.1.6`	`@flow/scss@1.1.6`
브랜치 기반	Semantic Versioning
커밋 해시로 롤백	명확한 버전 롤백

2. 팀 도입 성과

패키지 배포: 현재 @flow/scss v1.1.6 배포 완료. 패키지 4개 추가 배포
사용 프로젝트: 5개 프로젝트에서 활용 중
팀 만족도: config 설정 후엔 npm 표준 명령어 사용으로 학습 부담 제거

3. 운영 안정성

가용성: nginx + verdaccio 이중화로 안정성 확보
백업: 볼륨 마운트로 데이터 백업 자동화
모니터링: Docker 로그를 통한 접근 로그 및 에러 추적

• 배운 점과 향후 계획

핵심 교훈

표준을 따르는 것의 중요성
- npm 생태계의 표준 명령어와 워크플로우 활용
- 팀원들의 기존 지식과 경험 활용 가능
초기 복잡성 vs 장기 운영성
- 초기 설정의 복잡성보다 장기 운영의 안정성이 중요
- 표준 도구의 성숙한 생태계 활용
인프라 결정에서 고려해야 할 요소들
- 개발 편의성
- 운영 안정성
- 팀 전체의 학습 비용
- 장기적 확장성

향후 계획

모니터링 강화: 메트릭 수집 및 알람 시스템 구축
백업 자동화: 정기적인 storage 백업 및 복구 테스트

• 결론

때로는 원점으로 돌아가는 것이 정답이다.

Git 방식으로 우회했던 여정을 통해 Verdaccio의 진짜 가치를 더 명확하게 이해할 수 있었습니다. 초기의 복잡성이나 서버 운영 부담보다는 npm 생태계의 표준을 따르는 것이 팀 전체의 생산성과 서비스 안정성에 훨씬 유리했습니다.

현재 안정적으로 운영 중인 Verdaccio를 통해 앞으로도 더 많은 사내 패키지들을 체계적으로 관리해 나갈 예정입니다.

“돌아가는 길이 때로는 지름길이다” - 이번 프로젝트의 핵심 교훈입니다.

Yong's Park

Recent

배포 방식 비교