본문으로 건너뛰기

Nexus 프로젝트 Docker 수동 배포 가이드

등록일: 2026-04-26
내용: 본 문서는 로컬 환경에서 빌드된 Docker 이미지를 GitHub Container Registry(GHCR)를 통해 운영 서버에 배포하는 전 과정을 정리함.

1. 사전 준비 (GitHub Token 발급)​

GitHub Packages(GHCR)에 접근하기 위해서는 별도의 개인 액세스 토큰(PAT)이 필요함.

  • 발급 경로: Settings > Developer settings > Personal access tokens > Tokens (classic)
  • 권한(Scopes): write:packages, read:packages (repo 권한은 필요 시 선택)
  • 주의 사항: 토큰은 생성 시 1회만 노출되므로 반드시 별도 보관함.

2. 로컬 환경 작업 (Build & Push)​

로컬 PC에서 이미지를 생성하고 깃허브 창고로 업로드하는 단계임.

2.1 GHCR 로그인​

# Git Bash 등 터미널에서 실행
echo "발급받은_토큰_문자열" | docker login ghcr.io -u sleepzzzzz --password-stdin

2.2 이미지 태그 변경 (Alias 생성)​

로컬에서 테스트용으로 빌드한 이미지를 GHCR 규격에 맞는 이름으로 별칭을 부여함.

# docker tag [기존이미지]:[태그] [GHCR주소]/[아이디]/[이미지명]:[새태그]
docker tag nexus-system:docker-local ghcr.io/sleepzzzzz/nexus-system:latest

2.3 이미지 푸시 (Upload)​

생성된 이름표를 기반으로 깃허브 서버로 전송함.

docker push ghcr.io/sleepzzzzz/nexus-system:latest

3. 운영 서버 작업 (Pull & Run)​

N100 홈 서버(Ubuntu) 등 실제 서비스 환경에서 이미지를 구동하는 단계임.

3.1 기존 컨테이너 중지 및 삭제 (재배포 시)​

동일한 이름의 컨테이너가 이미 실행 중이라면 먼저 정리함.

docker stop nexus-system
docker rm nexus-system

3.2 서버 GHCR 로그인​

로컬에서와 동일하게 토큰을 사용하여 로그인함.

echo "발급받은_토큰_문자열" | docker login ghcr.io -u sleepzz --password-stdin

3.3 최신 이미지 다운로드 (Pull)​

창고에 올라온 따끈따끈한 최신 이미지를 내려받음.

docker pull ghcr.io/sleepzzzzz/nexus-system:latest

3.4 컨테이너 실행 (Run)​

운영 프로필(prod)과 시크릿 파일 경로를 연결하여 실행함.

docker run -d --name nexus-system \
  -p 8001:8001 \
  -e SPRING_PROFILES_ACTIVE=prod \
  -v "/sorc001/nexus/secrets:/app/secrets" \
  ghcr.io/sleepzzzzz/nexus-system:latest

4. 모니터링 및 검증​

4.1 로그 확인​

어플리케이션이 정상적으로 구동되는지 실시간 로그를 확인함.

docker logs -f nexus-system
  • 로그상에 The following 1 profile is active: "prod" 문구 확인 필요.

4.2 컨테이너 상태 확인​

docker ps -a
  • STATUS가 Up 상태인지, 포트 포워딩이 8001->8001로 잘 잡혔는지 확인함.

5. 보안 및 팁​

  • 로그아웃: 공용 서버이거나 보안이 중요하다면 작업 후 docker logout ghcr.io를 수행하여 토큰 정보를 삭제함.
  • 이미지 정리: 불필요하게 쌓인 옛날 이미지들은 docker image prune으로 정리하여 디스크 용량을 확보함.