🐳 도커 허브 무료 플랜의 한계 극복! 무제한 프라이빗 저장소 GHCR.io 활용법 완벽 가이드 🐙

talkit (71)in #kr • 14 days ago

안녕하세요 가야태자 @talkit 입니다.

오늘은 어제에 이어서 도커로 배포를 해볼텐데 솔직히 어제 가입한 도커허브가 서용이 없게 되었습니다. ㅠ.ㅠ

왜냐면, 제가 배포하는 도커 이미지가 두개인데 목적은 퍼블릭이지만, 처음에는 프라이빗으로 베타테스터를 초대해서 시작하고 합니다.

그런데 도커 이미지 하나만 프라이빗으로 가능하고 2개는 안된다고 해서 다른 방법을 사용해야할 것 같습니다.

그래서 오늘은 GHCR.IO(GitHub Container Registry)에 대해서 한번 더 설명 드리고, 배포는 내일 다시 진행 해야할 것 같습니다.

1. 💡 GHCR.io (GitHub Container Registry) 란?

GHCR은 GitHub에서 직접 제공하는 도커 및 OCI(Open Container Initiative) 컨테이너 이미지 저장소(Registry)입니다.

GitHub이 소스코드를 버전 관리하는 저장소라면, GHCR은 소스코드를 빌드하여 만든 도커 패키지(이미지)를 보관하고 배포하는 저장소입니다.

Registry 주소: ghcr.io
본 프로젝트 이미지 주소 예시:
ghcr.io/YOUR_GITHUB_ID/macdown-backend:latest (또는 :beta)
ghcr.io/YOUR_GITHUB_ID/macdown-frontend:latest (또는 :beta)

2. ⚡ 왜 Docker Hub 대신 GHCR.io인가? (주요 비교)

본 프로젝트는 백엔드(macdown-backend)와 프론트엔드(macdown-frontend) 2개의 도커 이미지를 독립적으로 빌드하여 배포합니다.

| 구분 | 🐳 Docker Hub (무료 플랜) | 🐙 GHCR (ghcr.io) ⭐ |

| :--- | :--- | :--- |

| 프라이빗 이미지 개수 | 단 1개만 무료 | 무제한 무료 ⭐ |

| 본 프로젝트 적합성 | ❌ (이미지 2개라 프라이빗 불가능) | ✅ (무제한 프라이빗 제공) |

| 권한/멤버 관리 | Docker Hub 사이트에서 별도 관리 | GitHub 저장소 초대로 코드+이미지 통합 관리 |

| 공개(Public) 전환 | 설정 복잡 | 버튼 클릭 한 번으로 손쉽게 전환 |

| 속도 및 제약 | 시간당 Pull 횟수 제한 (Rate Limit) | GitHub 글로벌 인프라 기반, 매우 높음 |

3. 🔐 GHCR.io 인증 및 로그인 (PAT 발급)

GHCR은 보안상 GitHub 계정의 일반 로그인 비밀번호 대신 Personal Access Token (PAT)을 사용해 로그인합니다.

3-1. PAT (Personal Access Token) 발급

GitHub 접속 → 우측 상단 프로필 이미지 → Settings
좌측 하단 Developer settings → Personal access tokens (classic) → Generate new token (classic) 선택
Note 입력 (예: macdown-ghcr-token)
Scope 선택:

write:packages (도커 이미지 Push 권한 / read:packages 자동 포함)
delete:packages (필요시 패키지 삭제 권한)

Generate token 클릭 후 생성된 토큰 문자열 복사

3-2. 터미널 도커 로그인

macOS / Linux (Bash):


echo "YOUR_PAT_TOKEN" | docker login ghcr.io -u YOUR_GITHUB_ID --password-stdin

Windows (PowerShell):


$env:GH_PAT="YOUR_PAT_TOKEN"

$env:GH_PAT | docker login ghcr.io -u YOUR_GITHUB_ID --password-stdin

위와 같이 진행하시면 된다고 합니다.

그래서 저도 실제로 해보겠습니다.

위 그림에서 create new token을 클릭 합니다.

classic을 선택하라고 하니깐 classic으로 ^^

위와 같이 넣코 체크한 다음에 쭉 아래로 내리시면 Generate token 버튼이 있습니다.

누르시면 되겠습니다.

오늘은 안보여 드릴껀데 ^^

다음 화면에 토큰이 나옵니다. 잘 복사해 두십시오.

그 다음에 로그인을 한번 해보겠습니다.

아참 윈도우에 도커를 설치 해야 합니다.

윈도우즈 파워쉘을 엽니다.

그리고, 도스창 비슷한 것이 나오면 .

wsl install

위 명령어를 먼저 입력 합니다.

혹시나 오류나면 질문 주십시오. wsl을 어떻게 설치하는지 알려 드리겠습니다.

저는 이미 설치 되어 있어서 wsl이 켜저서 빠져나와서

도커를 설치 했습니다.

winget install -e --id Docker.DockerDesktop

위 명령어를 치시면 됩니다.

그러면 관리자 권한으로 허가 하실꺼냐를 묻고 예 하면 설치를 해줍니다.

winget install -e --id Docker.DockerDesktop
찾음 Docker Desktop [Docker.DockerDesktop] 버전 4.85.0
이 응용 프로그램의 라이선스는 그 소유자가 사용자에게 부여했습니다.
Microsoft는 타사 패키지에 대한 책임을 지지 않고 라이선스를 부여하지도 않습니다.
다운로드 중 https://desktop.docker.com/win/main/amd64/235549/Docker%20Desktop%20Installer.exe
  ██████████████████████████████   596 MB /  596 MB
설치 관리자 해시를 확인했습니다.
패키지 설치를 시작하는 중...
설치 관리자가 관리자 권한으로 실행을 요청합니다. 프롬프트가 표시됩니다.
   - 사용자가 작업을 취소했습니다
설치 관리자가 종료 코드로 인해 실패함: 4294967291
PS C:\Users\kjh0523> winget install -e --id Docker.DockerDesktop
찾음 Docker Desktop [Docker.DockerDesktop] 버전 4.85.0
이 응용 프로그램의 라이선스는 그 소유자가 사용자에게 부여했습니다.
Microsoft는 타사 패키지에 대한 책임을 지지 않고 라이선스를 부여하지도 않습니다.
설치 관리자 해시를 확인했습니다.
패키지 설치를 시작하는 중...
설치 관리자가 관리자 권한으로 실행을 요청합니다. 프롬프트가 표시됩니다.
설치 성공

처음에 글적고 있는데 창이 떠서 ㅋㅋㅋ 아니오를 눌렀나 봅니다.

꼭 예 또는 확인을 누르십시오.

$env:GH_PAT="YOUR_PAT_TOKEN"

$env:GH_PAT | docker login ghcr.io -u YOUR_GITHUB_ID --password-stdin

저위에 윈도우즈 로그인 명령어가 저렇게 되어 있습니다.

YOUR PAT TOKEN에 아까 저장해둔 토큰을 넣습니다.

YOUR_GITHUB_ID는 여러분의 github 아이디 입니다. ^^

도커 명령어가 없다고 오류납니다.

여러분들은 새 파워쉘 창을 띄우고 하십시오 ^^

 $env:GH_PAT | docker login ghcr.io -u YOUR_GITHUB_ID --password-stdin
Login Succeeded

저는 ghcr.io 저장소에 로그인이 되었습니다.

다음은 본 프로젝트의 이미지 빌드부터 서버/테스터 배포까지의 흐름입니다.


[개발 PC (Mac / Windows)]

│

│ 1. 멀티 아키텍처 빌드 & Push

│ - macOS: ./scripts/build-and-push.sh

│ - Windows: .\scripts\build-and-push.ps1

▼

[GHCR.io (GitHub Packages)]

- ghcr.io/username/macdown-backend:latest

- ghcr.io/username/macdown-frontend:latest

│

│ 2. docker compose pull (서버 / 테스터)

▼

[클라우드 서버 / 테스터 PC] ──▶ Docker Compose 실행 (8090 포트)

이제 도커 저장소에 가입도 하고 로그인도 했으니까

실제로 도커에 컨테이너를 만들고

올린 다음에 깃허브 이미지를 내려받아서 docker compose 해보는 것만 남았습니다.

그리고, 이걸 일단윈도우즈에서도 해보고

서버에서도 한번 해보겠습니다.

감사합니다.

https://talkit.tistory.com

#talkit #kr-dev #docker #ghcr.io #docker-hub