들어가며
최근 Node.js 생태계에서는 node_modules 관리 효율화를 위해 심볼릭 링크를 활용하는 패키지 매니저들이 주목받고 있습니다. 특히 pnpm과 같은 도구들은 디스크 공간 절약과 설치 속도 개선을 위해 심볼릭 링크를 적극적으로 활용하고 있습니다.
하지만 이러한 프로젝트를 AWS의 CI/CD 파이프라인(CodeCommit → CodeBuild → CodeDeploy)에 적용할 때 몇 가지 까다로운 문제에 직면하게 됩니다. 이번 포스트에서는 이러한 문제들을 살펴보고 실제 해결 방법을 다뤄보겠습니다.
문제 상황
1. CodeBuild의 심볼릭 링크 처리
기본적으로 CodeBuild는 빌드 결과물을 S3에 업로드할 때 심볼릭 링크를 포함하지 않습니다. 이는 Node.js 프로젝트 중 pnpm을 사용하는 프로젝트에서 정상적인 애플리케이션 실행을 하지 못하는 문제를 일으킬 수 있습니다.
2. CodeDeploy의 파일 복사 문제
CodeDeploy agent가 빌드 결과물을 실제 배포 위치로 복사할 때도 문제가 발생합니다. 이는 CodeDeploy agent의 내부 구현 방식 때문인데, Ruby로 작성된 agent가 FileUtils.copy() 대신 FileUtils.copyEntry()를 사용하여 심볼릭 링크를 제대로 처리하지 못하는 것이 원인입니다.
해결 방법
1. CodeBuild 설정 수정
먼저 buildspec.yml 파일에 심볼릭 링크를 포함하도록 설정을 추가해야 합니다:
version: 0.2
phases:
install:
runtime-versions:
nodejs: 20
pre_build:
commands:
- npm install -g pnpm
- pnpm install
build:
commands:
- pnpm run build:dev
artifacts:
files:
- '**/*'
enable-symlinks: yes # 심볼릭 링크 포함 설정enable-symlinks 옵션을 활성화하게 되면, artifacts의 결과 파일에도 심볼릭 링크를 포함하게 됩니다.
2. CodeDeploy 스크립트 개선
appspec.yml에서 단순히 파일을 복사하는 대신, 배포 스크립트에서 심볼릭 링크를 올바르게 처리하도록 수정해야 합니다:
문제가 발생하는 지점은 다음과 같습니다.
# appspec.yml
files:
- source: /
destination: /data/application/opt/codedeploy-agent/deployment-root/ 내부에 있는 파일을 /data/application으로 복사를 해오는 과정에서 심볼릭 링크를 복사해오지 못하는 문제가 발생하는 것이기 때문에, 배포 스크립트(deploy.sh)에서 다음과 같이 처리합니다:
cd /data/application/
npm install -g pnpm
# 심볼릭 링크를 포함한 node_modules 복사
if [ ! -z "$DEPLOYMENT_ID" ]; then
rm -rf /data/application/node_modules
cp -ar /opt/codedeploy-agent/deployment-root/$DEPLOYMENT_GROUP_ID/$DEPLOYMENT_ID/deployment-archive/node_modules /data/application/
else
echo "DEPLOYMENT_ID is not set. Skipping node_modules operations."
fi
# 애플리케이션 실행 (예시)
nohup pnpm start > /data/logs/application.log 2>/data/logs/error.log &여기서 핵심은 cp -ar 명령어를 사용하여 심볼릭 링크를 보존한 채로 파일을 복사하는 것입니다.
구현 세부 사항 설명
- 심볼릭 링크 보존:
-a옵션은 파일의 속성을 보존하고,-r옵션은 디렉토리를 재귀적으로 복사합니다. - 기존 node_modules 제거: 새로운 복사 전에 기존
node_modules를 제거하여 충돌을 방지합니다.
마치며
이러한 방식으로 심볼릭 링크를 사용하는 Node.js 프로젝트도 AWS의 CI/CD 파이프라인에서 안정적으로 배포할 수 있습니다. 현재 CodeDeploy agent의 제한사항을 우회하는 방법이지만, 실제 프로덕션 환경에서도 안정적으로 동작하는 해결책입니다.
향후 AWS가 이 문제를 네이티브하게 해결할 때까지, 위 방법으로 심볼릭링크 빌드/Deploy 작업을 진행할 수 있습니다.
참고 자료
