홈서버에 Docker Registry 구축

ℹ️ Harbor
CNCF에서 graduated된 안정성 있는 오픈소스 프로젝트로, Docker Registry 구축 및 Web GUI를 통한 관리 기능을 제공.

구축 환경

서버1

• 홈네트워크 외부로부터 80, 443 포트를 포워딩 받는 'web gateway' 역할
• apache2 웹서버 및 prometheus 모니터링 서버 구동 중

서버2

• Harbor를 설치 및 구동시킬 서버
• registry는 이미지 push/pull 작업(= Disk I/O)이 주 기능이므로 SDD 사용중인 서버2에 Harbor 세팅

아키텍처

Apache2

서버1의 웹 서버로, 홈네트워크 외부로부터의 80, 443포트 트래픽을 전달 받음.

Prometheus

시스템/프로세스 모니터링 시스템으로, Harbor로부터 지표(metric)을 수집.

Harbor

Docker Private Registry + Web GUI.
Docker를 통해 구동.

[구축] 서버1 세팅

apache2, letsencrypt(certbot)은 설치되어 있다고 가정

1. SSL 인증서 발급 (Let's Encrypt)

# apache plugin 설치
sudo apt install certbot python3-certbot-apache


# 인증서 발급
sudo certbot --apache \
-d docker.hyeonwoo.com

2. apache2 설정

/etc/apache2/sties-available/docker-ssl.conf 파일 생성 및 아래와 같이 작성

<IfModule mod_ssl.c>
        <VirtualHost *:443>
                ServerName docker.hyeonwoo.com

                  # SSL 인증서 경로 지정
                SSLCertificateFile /etc/letsencrypt/live/docker.hyeonwoo.com/cert.pem
                SSLCertificateKeyFile /etc/letsencrypt/live/docker.hyeonwoo.com/privkey.pem
                SSLCertificateChainFile /etc/letsencrypt/live/docker.hyeonwoo.com/chain.pem

                  # 프록시 설정
                ProxyPreserveHost On
                ProxyRequests Off
                AllowEncodedSlashes NoDecode

                ProxyPass / http://10.10.10.52:5050/
                ProxyPassReverse / http://10.10.10.52:5050/

                # Harbor는 WebSocket도 쓰니까 추가
                RewriteEngine on
                RewriteCond %{HTTP:Upgrade} =websocket [NC]
                RewriteCond %{HTTP:Connection} upgrade [NC]
                RewriteRule ^/(.*)  ws://10.10.10.52:5050/$1 [P,L]


                RequestHeader set X-Forwarded-Proto "https"
                RequestHeader set X-Forwarded-Port "443"
        </VirtualHost>
</IfModule>

모듈/사이트 활성화

# 프록시 기능을 지원하는 apache2 모듈 활성화
sudo a2enmod proxy proxy_http

# 위에서 작성한 virtual host 활성화
cd /etc/apache2/sites-available
sudo a2ensite docker-ssl

# apache2 재시작
sudo systemctl restart apache2

[구축] 서버2

docker 설치되어 있다고 가정

사용할 디렉터리
[working dir] /var/harbor
[data dir] /var/harbor/data
[log dir] /var/log/harbor

Harbor 다운로드

# 디렉터리 준비
sudo mkdir -p /var/harbor/data

cd /var/harbor

# online installer 다운로드 (현시점 최신버전 2.13.2, 필요 시 아래 url에서 버전명 수정하여 다운로드 진행)
sudo wget https://github.com/goharbor/harbor/releases/download/v2.13.2/harbor-online-installer-v2.13.2.tgz

# 압축 해제
sudo tar xvf harbor-online-installer-v2.13.2.tgz

다운로드 후 /var/harbor 디렉터리 구조

/var/harbor
├── data
├── harbor # 압축해제하면 생기는 디렉터리
└── harbor-online-installer-v2.13.2.tgz

초기 설정값 지정

1. 설정파일 생성 (제공된 템플릿파일을 복사)
2. cd harbor sudo cp harbor.yml.tmpl harbor.yml
3. harbor.yml 파일 수정

❗️ 기본 템플릿에 모든 항목이 다 적혀있으므로 주석해제 또는 value 변경만 하면 됨. 즉, 그대로 복사해서 사용하면 에러 발생 위험 있음

hostname: docker.hyeonwoo.com

http:
  port: 5050

data_volume: /var/harbor/data
external_url: https://docker.hyeonwoo.com

log:
  # options are debug, info, warning, error, fatal
  level: info
  local:
    rotate_count: 5
    # default: bytes. k, M, G (k 소문자 맞음)
    rotate_size: 10M
    location: /var/log/harbor

metric:
  enabled: true
  port: 9090
  path: /metrics

harbor 설치

sudo ./install.sh

이후 harbor 컨테이너가 실행되고, 이 때 harbor.yml 파일의 내용을 초기 설정값으로 취함.

install.sh 파일을 살펴보면, 간략하게 다음 과정을 실행하는 것을 알 수 있음.

• 동일 디렉터리의 commom.sh파일 실행
• 동일 디렉터리의 prepare 파일을 실행
• docker compose up -d (이미 실행중이면 down 먼저 하고 up 실행)

/var/harbor/harbor
├── LICENSE
├── common
├── common.sh
├── docker-compose.yml
├── harbor.yml
├── harbor.yml.tmpl
├── install.sh
└── prepare

⬇️ 실제 install.sh 파일 내용 (일부)

# ...

DIR="$(cd "$(dirname "$0")" && pwd)"
source $DIR/common.sh

#...

./prepare $prepare_para
echo ""

if [ -n "$DOCKER_COMPOSE ps -q"  ]
    then
        note "stopping existing Harbor instance ..." 
        $DOCKER_COMPOSE down -v
fi
echo ""

h2 "[Step $item]: starting Harbor ..."
$DOCKER_COMPOSE up -d

success $"----Harbor has been installed and started successfully.----"

ℹ️ harbor 접속을 위한 초기 admin 계정
ID: admin
PW: Harbor12345
❗️ install.sh 실행하기 전에 harbor.yml에 harbor_admin_password 설정값을 지정하여 초기 비밀번호를 다른 값으로 지정할 수 있지만, 민감정보를 파일에 남기고 싶지 않아서 install 후 harbor에 접속하여 비밀번호 변경함.

방화벽 설정

harbor 접속을 위한 5050포트, 지표 수집을 위한 9090포트 허용

sudo ufw allow 5050
sudo ufw allow 9090

동작 확인

✅ 브라우저에서 https://docker.hyenonwoo.com 에 접속하여 로그인 테스트
✅ 홈네트워크에 VPN 연결 후, 브라우저에 http://10.10.10.52:9090/metrics url 입력하여 지표 조회 테스트
✅ 도커 로그인, 이미지 푸시 테스트

• docker login docker.hyeonwoo.com
• docker push docker.hyeonwoo.com/<project>/<image>:<tag>

harbor.yml 변경사항 반영

로그레벨, 로그 로테이팅, 포트 등 설정값을 변경했다면 아래 명령으로 반영

cd /var/harbor/harbor
docker compose down
./prepare # 실행가능한 shell script 파일
docker compose up -d

❗️ harbor_admin_password를 비롯한 몇몇 설정값은 맨처음 설치(install.sh 실행) 시에만 반영되고 이후에는 값을 변경하더라도 반영되지 않음

참고 문서

• Harbor 공식 문서
• https://kimmj.github.io/harbor/what-is-harbor/