Unregistry & docker pussh: 개발자 친화형 초경량 이미지 레지스트리

Unregistry는 Docker 데몬의 로컬 저장소를 직접 활용하여 이미지를 저장하고 서빙하는 초경량 컨테이너 이미지 레지스트리입니다. 기존 Docker 이미지 배포 방식에 존재하던 불편함을 해소하기 위해 만들어졌으며, 특히 다음과 같은 사용자의 고충을 해결합니다:

기존 방식	문제점
Docker Hub, GHCR 등 퍼블릭 레지스트리	코드 노출 위험 또는 유료 구독 필요
자체 레지스트리 운영	추가 인프라 및 보안 관리 필요
docker save; ssh docker load	전체 이미지 전송 (중복 레이어 포함)
원격 서버에서 재빌드	시간 소모, 실패 가능성 ↑

🛠️ “그냥 A에서 B로 이미지만 옮기고 싶은데 왜 이렇게 복잡한가요?”
   → Unregistry + docker pussh가 그 해답입니다.

핵심 기능 요약

기능	설명
로컬 Docker 스토리지 활용	별도 blob 저장소 없이 Docker 데몬의 이미지 캐시 직접 활용
SSH 기반 전송 (docker pussh)	원격 서버로 누락된 레이어만 전송 (빠르고 효율적)
레지스트리 없이 사용 가능	중간 서버, 인증, 공개 설정 없이도 이미지 전송 가능
air-gapped 환경 대응	인터넷 없는 환경에서도 전송 가능 (사전 이미지 preload 지원)
containerd 기반 이미지 저장	레이어 중복 없이 효율적 스토리지 사용

작동 방식 (내부 흐름)

docker pussh myapp:latest user@server 실행 시 다음 절차가 자동 진행됩니다.

1. SSH 연결: 로컬에서 원격 서버로 SSH 연결 생성
2. 원격에서 unregistry 실행: 일시적으로 Unregistry 컨테이너 실행
3. 로컬 포트 포워딩: localhost:포트 → 원격 unregistry로 포트 포워딩
4. docker push 실행: 전송되지 않은 레이어만 push (rsync 유사)
5. 이미지 등록 완료: 이미지가 즉시 원격 Docker에서 사용 가능
6. 종료: unregistry 컨테이너 자동 종료 및 SSH 세션 종료

300x250

설치 방법

🔸 Homebrew (macOS/Linux)

brew install psviderski/tap/docker-pussh
mkdir -p ~/.docker/cli-plugins
ln -sf $(brew --prefix)/bin/docker-pussh ~/.docker/cli-plugins/docker-pussh

🔸 수동 설치

mkdir -p ~/.docker/cli-plugins
curl -sSL https://raw.githubusercontent.com/psviderski/unregistry/v0.2.1/docker-pussh \
  -o ~/.docker/cli-plugins/docker-pussh
chmod +x ~/.docker/cli-plugins/docker-pussh

🔸 Debian

curl -sS https://debian.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | \
  sudo gpg --dearmor --yes -o /etc/apt/trusted.gpg.d/debian.griffo.io.gpg

echo "deb https://debian.griffo.io/apt $(lsb_release -sc) main" | \
  sudo tee /etc/apt/sources.list.d/debian.griffo.io.list

sudo apt update
sudo apt install -y unregistry docker-pussh

🔸 Windows

• 공식 지원 없음
• WSL2를 통해 위 Linux 방식 사용 가능

사용법

🔸 기본 전송

docker pussh myapp:latest user@host

🔸 SSH 키 지정

docker pussh myapp:latest user@host -i ~/.ssh/id_rsa

🔸 SSH 포트 지정

docker pussh myapp:latest user@host:2222

🔸 플랫폼 지정 (멀티 플랫폼 이미지 지원)

docker pussh myapp:latest user@host --platform linux/amd64

전제 조건 (요구 사항)

로컬 머신

• Docker CLI 19.03+ (플러그인 지원)
• OpenSSH client

원격 서버

• Docker 데몬 실행 중
• SSH 사용자에 docker 실행 권한 (비루트 계정은 docker 그룹에 포함)
• 최초 사용 시 ghcr.io/psviderski/unregistry:latest 이미지를 pull할 수 있어야 함 (또는 사전 preload)

Air-Gapped 환경 대응

# 인터넷 있는 서버에서
docker pull ghcr.io/psviderski/unregistry:latest
docker save ghcr.io/psviderski/unregistry:latest | ssh user@server docker load

containerd 이미지 스토어 고려사항

설정 여부	효과
✅ 사용 (권장)	전송된 이미지가 곧바로 Docker에서 사용 가능, 중복 저장 없음
❌ 미사용 (기본 Docker 동작)	이미지가 containerd와 Docker에 이중 저장됨, 디스크 공간 낭비

containerd 이미지 목록 확인/삭제

sudo ctr -n moby images ls
sudo ctr -n moby images rm <image>

📚 참고: Docker Engine에서 containerd image store 활성화 방법은 공식 문서 참고

주요 활용 사례

1. 프로덕션 서버에 직접 배포

docker build -t myapp:1.2.3 .
docker pussh myapp:1.2.3 deploy@prod-server
ssh deploy@prod-server docker run -d myapp:1.2.3

2. CI/CD 파이프라인에서 레지스트리 제거

- name: Build and deploy
  run: |
    docker build -t myapp:${{ github.sha }} .
    docker pussh myapp:${{ github.sha }} deploy@staging-server

3. Air-Gapped 환경 이미지 배포

• 공용 레지스트리에 접근할 수 없는 폐쇄망에서 활용
• 사전 이미지 preload 후 내부에 직접 전달

4. Standalone 로컬 레지스트리

docker run -d -p 5000:5000 --name unregistry \
  -v /run/containerd/containerd.sock:/run/containerd/containerd.sock \
  ghcr.io/psviderski/unregistry

docker tag myapp:latest localhost:5000/myapp:latest
docker push localhost:5000/myapp:latest

점검 포인트

• SSH 접속 계정은 최소 권한 원칙 적용 (docker 그룹 제한)
• Docker 소켓(/var/run/docker.sock or /run/containerd/containerd.sock) 접근 권한 점검
• 방화벽 설정으로 외부 접근 제어
• Unregistry는 인증 기능이 없으므로 공개망 사용 금지
• 이미지 캐시 누적으로 인한 디스크 점검 필요

고급 설정

🔸 SSH 설정 파일 사용

# ~/.ssh/config
Host prod-server
    HostName server.example.com
    User deploy
    Port 2222
    IdentityFile ~/.ssh/deploy_key

docker pussh myapp:latest prod-server

참고 자료

• 🔗 GitHub: https://github.com/psviderski/unregistry
• 📚 문서: Docker Engine - containerd image store
• 🧪 관련 도구: Spegel, Docker Distribution, Harbor

 

Unregistry는 “Docker 이미지 이동”이라는 단순한 목적을, 빠르고 간단하게, 그리고 효율적으로 해결하는 도구입니다. 레지스트리 없는 CI/CD, 오프라인 배포, 개발-운영간 이미지 동기화 등 다양한 환경에서 매우 실용적이며, 복잡한 레지스트리 운영 부담을 없애고 싶은 사용자에게 최고의 선택입니다.