나만의 이미지 레지스트리
자체 레지스트리가 필요한 경우, 비밀번호와 인증서로 설정하는 방법, 소모하는 디스크 용량, 오래된 이미지의 저장소로 전락하지 않게 하는 방법을 다뤄요.
업데이트 2026년 8월 23일
레지스트리는 이미지 저장소예요. 직접 운영해야 하는 경우는 세 가지예요. 이미지가 비공개라 자체 인프라 밖으로 나가면 안 될 때, 빌드가 자주 일어나 외부 다운로드 제한이 발목을 잡을 때, 같은 것을 여러 머신에 배포할 때예요.
간단한 방법: registry:2
services:
registry:
image: registry:2
restart: unless-stopped
environment:
REGISTRY_AUTH: htpasswd
REGISTRY_AUTH_HTPASSWD_REALM: Registry
REGISTRY_AUTH_HTPASSWD_PATH: /auth/htpasswd
REGISTRY_STORAGE_DELETE_ENABLED: "true"
volumes:
- ./data:/var/lib/registry
- ./auth:/auth:ro
ports:
- "127.0.0.1:5000:5000"
비밀번호는 이렇게 만드세요:
mkdir -p auth
docker run --rm --entrypoint htpasswd httpd:2 -Bbn deploy 'long-password' > auth/htpasswd
docker compose up -d
포트를 외부에 노출하지 마세요. 인증서를 붙인 웹 서버가 레지스트리 앞에 서야 해요. Docker는 서드파티 레지스트리와 HTTP로 통신하는 것을 거부해요. 당연한 게, 그 통로로 실행 가능한 코드가 여러분의 머신에 들어오니까요.
사용법
docker login registry.example.com
docker tag myapp:1.5.0 registry.example.com/myapp:1.5.0
docker push registry.example.com/myapp:1.5.0
docker pull registry.example.com/myapp:1.5.0
curl -u deploy https://registry.example.com/v2/_catalog
curl -u deploy https://registry.example.com/v2/myapp/tags/list
docker login 후 자격 증명은 ~/.docker/config.json에 평문으로 남아요(base64는 암호화가 아니에요). 빌드 머신에서는 읽기 전용 권한만 가진 별도 계정을 만드세요.
크기 제한도 정리 작업도 없는 레지스트리는 디스크를 채우는 가장 빠른 길이에요. 빌드할 때마다 레이어가 쌓이고, 태그를 지워도 공간은 비워지지 않아요. 가비지 컬렉션이 필요하죠. 40 GB짜리 VDS-1에서 활발한 프로젝트의 레지스트리는 몇 주 만에 디스크를 가득 채울 거예요.
정리
태그 삭제와 그에 따른 가비지 컬렉션:
docker compose exec registry registry garbage-collect \
--delete-untagged /etc/docker/registry/config.yml
가비지 컬렉션이 도는 동안에는 레지스트리를 멈춰야 해요. 그러지 않으면 동시에 들어온 push가 레이어를 잃을 수 있어요:
docker compose stop registry
docker compose run --rm registry registry garbage-collect --delete-untagged /etc/docker/registry/config.yml
docker compose start registry
이 작업을 일주일에 한 번 예약 작업으로 설정하고 디스크 공간을 계속 지켜보세요.
대안: Git 서버에 딸린 레지스트리
이미 Forgejo나 Gitea를 구성했다면, 여기에는 Docker 이미지를 포함한 패키지 저장소가 내장되어 있어요. 별도 서비스가 필요 없죠. 같은 계정으로 접근하고, 이미지가 코드 옆에 보여요. 작은 프로젝트에는 독립적인 registry:2보다 이쪽이 더 편해요.