Unregistry – “docker push”를 레지스트리 없이 서버에 직접 전송

14 hours ago 1

Unregistry는 외부 레지스트리 없이 Docker 이미지를 원격 서버에 직접 전송할 수 있는 오픈소스 툴임
docker pussh 명령으로 SSH를 통해 원격 서버에 이미지를 효율적으로 전송하며, 이미 존재하는 레이어는 건너뜀
전통적인 Docker Hub, 자체 레지스트리, save/load 방식의 복잡함과 비효율성을 해소함
운영 환경 배포, CI/CD, 폐쇄망 환경 등에서 빠르고 안전한 이미지 이전이 큰 장점임
설치, 사용, 요구 사항이 매우 단순하며, 추가 서비스 운영이나 포트 노출이 필요 없음

Unregistry 소개 및 주요 장점

Unregistry는 Docker 데몬의 스토리지에서 직접 이미지를 저장 및 제공하는 경량 이미지 레지스트리임
docker pussh 커맨드를 사용하면 SSH를 통해 외부 레지스트리 없이 이미지를 바로 원격 Docker 서버로 이동 가능함
전송 시 이미 서버에 존재하는 레이어는 제외하고 필요한 부분만 빠르게 전송하는 효율성 제공함

기존 Docker 이미지 배포의 문제점

이미지를 로컬에서 빌드한 후 서버로 전송할 때 선택지가 아래와 같음
- Docker Hub/GitHub Container Registry: 코드가 외부에 공개되거나 개인 저장소 사용 시 비용 발생함
- 자체 레지스트리: 별도 서비스 운영 및 보안, 스토리지 관리 부담 증가함
- Save/Load: 전체 이미지를 항상 전송하여 비효율 발생함
- 서버에서 직접 재빌드: 시간 및 서버 리소스 낭비와 디버깅 문제 발생함

Unregistry 솔루션

docker pussh myapp:latest user@server 명령 한 번으로 중간 저장소 없이 직접 전송 가능함
추가적인 레지스트리 설정, 포트 노출, 스토리지 준비, 구독 필요 없음
전송 과정
- SSH 터널을 원격 서버로 연결함
- 임시로 unregistry 컨테이너 실행함
- 랜덤 로컬 포트와 unregistry 포트 연결함
- docker push로 존재하지 않는 레이어만 전송함 (즉시 사용 가능)
- unregistry 컨테이너와 SSH 터널 종료함
rsync처럼 단순·효율적 방식임
본 프로젝트는 Uncloud에서 다중 Docker 호스트로 컨테이너를 배포하는 과정의 복잡함을 단순화하기 위해 개발됨

사용 예시

배포 환경으로 직접 이미지 전송

로컬에서 빌드 후 직접 운영 서버로 push함
- docker build --platform linux/amd64 -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

CI/CD 파이프라인

레지스트리 복잡성 없이 빌드 및 배포 지원
- GitHub Action YAML 등에서 직접 전송 사용 가능

홈랩, 인터넷이 없는 폐쇄망 환경

이미지 인터넷 공개 없이 격리 네트워크에 안전하게 전송함

사용 방법

SSH 사용자 계정이 원격에서 docker 명령을 사용할 수 있어야 함
SSH 프라이빗 키나 커스텀 SSH 포트 등 추가 옵션 지원함
멀티 플랫폼 이미지 전송도 지원 (containerd 기반일 경우)

요구 사항

로컬 환경

Docker CLI (플러그인 지원, 19.03+)
OpenSSH 클라이언트

원격 서버

Docker가 설치 및 실행 중이어야 함
ssh 사용자가 docker 권한을 소유해야 하며, 필요 시 패스워드 없는 sudo docker 실행 가능해야 함
containerd image store 사용 시 성능이 향상됨
- /etc/docker/daemon.json에 다음 설정 추가 및 docker 재시작 필요 { "features": { "containerd-snapshotter": true } }

고급 사용법

로컬 독립형 레지스트리로 사용

추가 컴포넌트 없이 unregistry를 로컬 레지스트리로 손쉽게 운영 가능함
도커 명령으로 deploy 및 push 가능

SSH 커스텀 옵션 활용

SSH config 파일을 활용해 추가 인증, 포트 등 조건에 맞는 세부 설정 가능

기여 및 커뮤니티

버그 발견 시 GitHub 이슈 등록 활용
Uncloud Discord 커뮤니티에서 피처·로드맵·구현 세부 논의 가능

영감과 참고 오픈소스

Spegel: containerd 기반의 P2P 컨테이너 이미지 레지스트리 구현에서 영감 받음
Docker Distribution: 실제 레지스트리 구현 베이스로 사용됨

요약

Unregistry는 Docker 이미지를 쉽고 빠르게 원격 서버로 직접 이전할 수 있는 툴로 레지스트리 구축 및 관리 부담을 없앰
운영 환경 배포, CI/CD, 폐쇄망 등 다양한 시나리오에서 강력한 이점을 제공함
서버와 관리자가 단순하게 이미지만 절차 없이 이동하고 싶은 경우 매우 적합함

Read Entire Article