개인 서버에 Docker Registry 직접 구축해서 사용하기

JSCODE 박재성

2025-12-10

1. OpenSSL을 활용해 자체 서명된 SSL 인증서 생성하기

$ mkdir ~/docker-registry/certs
$ cd ~/docker-registry/certs

# $ openssl req -newkey rsa:4096 -nodes -sha256 -keyout {key 파일명}.key -x509 -days {인증서 유효기간} -out {crt 파일명}.crt -subj
$ openssl req -newkey rsa:4096 -nodes -sha256 -keyout registry.key -x509 -days 36500 -out registry.crt

• .crt 파일 : 공개키(Public Key)를 포함한 인증서(Certificate) 파일
• HTTPS 통신에서 클라이언트가 서버한테 통신을 보낼 때 공개키를 활용해 암호화를 해서 보냄.
• 평상시에 클라이언트가 .crt 파일을 가지고 있지 않고, 클라이언트가 서버에 HTTPS 요청을 보내면 그 때 서버가 클라이언트한테 .crt 파일을 전달한다. 이게 바로 SSL Handshake이다.

• .key 파일 : 개인키(Private Key) 파일
• 절대 유출되면 안 됨. 서버만 가지고 있어야 함.
• HTTPS 통신에서 클라이언트가 보낸 암호화된 데이터를 복호화할 때 사용.

2. Compose 파일 작성하기

$ cd ~/docker-registry
$ vi compose.yml

services:
  docker-registry:
    image: registry:3
    container_name: docker-registry
    restart: always
    ports:
      - "5000:5000"
    environment:
      REGISTRY_HTTP_TLS_CERTIFICATE: /certs/registry.crt
      REGISTRY_HTTP_TLS_KEY: /certs/registry.key
      REGISTRY_HTTP_ADDR: 0.0.0.0:5000
    volumes:
      - ./data:/var/lib/registry
      - ./certs:/certs

• registry.crt, registry.key라고 입력한 값은, 1번 과정에서 SSL 인증서를 발급할 때 만든 파일명과 동일하게 작성해야 한다.

3. 도메인이 없는 채로 HTTPS 통신을 하기 위한 설정 추가

{
  "insecure-registries": [
    "172.30.1.37:5000" # 자신이 구축한 Docker Registry의 접근 IP 주소 기입
  ]
}

$ sudo systemctl daemon-reload
$ sudo systemctl restart docker

1. Docker Desktop 실행

2. 오른쪽 상단 톱니바 → Settings

3. 왼쪽 메뉴에서 Docker Engine 클릭

4. JSON에 아래처럼 추가:

{
  "insecure-registries": [
    "172.30.1.37:5000"
  ]
}

4. HTTPS 통신이 정상적으로 잘 되는 지 테스트하기

1. docker-registry 컨테이너 실행시키기

$ docker compose up --build -d
$ docker ps # 컨테이너가 잘 떴는지 확인
$ docker logs [컨테이너 ID] # 컨테이너 로그에 에러 메시지 없는 지 확인

 

2. curl 활용해 HTTPS 통신 잘 되는 지 확인하기
Docker Registry가 설치된 환경에서 아래 명령어를 입력해 통신을 해보자.

$ curl -k https://localhost:5000/v2/_catalog

아래와 같이 출력된다면 정상적으로 잘 적용된 것이다.



 
그리고 외부의 다른 컴퓨터에서 Docker Registry로 HTTPS 통신을 해보자.

# curl -k https://{Docker Registry로 접근할 IP}:5000/v2/_catalog
$ curl -k https://172.30.1.37:5000/v2/_catalog

아래와 같이 출력이 된다면 역시나 잘 적용된 것이다.

5. 기본 인증 설정하기

1. Docker Registry에 접근할 때 사용할 아이디, 패스워드 설정하기
Docker Registry를 사용하려면 HTTPS 적용 이외에도 기본적인 인증 과정을 추가해주어야만 사용이 가능하다. 그래서 아이디, 패스워드를 입력하고 Docker Registry를 사용하는 과정을 추가해줄 것이다.

$ mkdir ~/docker-registry/auth
$ cd ~/docker-registry/auth

$ docker run \
  --entrypoint htpasswd \
  httpd:2 -Bbn {아이디} {비밀번호} > htpasswd

 
인증 파일이 잘 생성됐는 지 확인해보자. 아래와 같이 명령어를 입력했을 때 아래와 같이 출력된다면 정상적으로 잘 생성된 것이다.



 

2. compose.yml 파일 수정하기
compose.yml

services:
  docker-registry:
    image: registry:3
    container_name: docker-registry
    restart: always
    ports:
      - "5000:5000"
    environment:
      REGISTRY_HTTP_TLS_CERTIFICATE: /certs/registry.crt 
      REGISTRY_HTTP_TLS_KEY: /certs/registry.key
      REGISTRY_HTTP_ADDR: 0.0.0.0:5000
      REGISTRY_AUTH: htpasswd
      REGISTRY_AUTH_HTPASSWD_REALM: "Registry Realm"
      REGISTRY_AUTH_HTPASSWD_PATH: /auth/htpasswd
    volumes:
      - ./data:/var/lib/registry
      - ./certs:/certs
      - ./auth:/auth

 

3. 컨테이너 다시 실행시키기

$ cd ~/docker-registry
$ docker compose up --build -d

 

4. 잘 작동하는 지 확인하기
Docker Registry가 설치된 환경에서 먼저 확인해보자.

# docker login {Docker Registry로 접근할 IP}:5000
$ docker login 172.30.1.37:5000

# docker login {Docker Registry로 접근할 IP}:5000
$ docker login 172.30.1.37:5000

이렇게까지 설정하면 Docker Resitry 구축이 끝이다~~~~