QueryPie Docker 이미지 로컬 저장 스크립트 사용 가이드

1 소개
2 사전 요구사항
3 설치 과정 요약
4 단계별 가이드
5 출력 결과
6 문제해결
7 최종 확인 사항

소개

이 가이드는 파트너사 기술 담당자가 save_docker_image.sh 스크립트를 사용하여 Harbor 레지스트리에서 QueryPie 및 QueryPie-Tools Docker 이미지를 가져와 로컬 환경에 .tar 파일로 저장하는 방법을 안내합니다. 스크립트는 이미지 다운로드, 저장, 중복 파일명 처리, 기존 동일 버전 이미지 삭제 등의 기능을 자동화합니다.

대상 독자: 파트너사 기술 담당자
예상 소요 시간: 네트워크 속도 및 이미지 크기에 따라 몇 분에서 수십 분 소요될 수 있습니다.

사전 요구사항

스크립트를 성공적으로 실행하기 위해 다음 사항을 확인하고 준비해야 합니다.

Docker 설치: 스크립트를 실행할 시스템에 Docker가 설치되어 있어야 합니다.
- 📝 Docker가 설치되어 있지 않다면, 공식 Docker 문서를 참조하여 설치를 진행하십시오.
save_docker_image.sh 스크립트 파일: 해당 스크립트 파일을 보유하고 있어야 합니다.
Harbor 레지스트리 접근 권한: harbor.chequer.io 레지스트리에 접근 가능한 사용자 계정 (사용자명 및 비밀번호)이 필요합니다.
충분한 디스크 공간: 다운로드할 Docker 이미지와 생성될 .tar 파일을 저장할 충분한 디스크 여유 공간이 필요합니다.
인터넷 연결: Harbor 레지스트리에서 이미지를 다운로드하기 위해 안정적인 인터넷 연결이 필요합니다.
기본 리눅스 터미널 사용 지식: 터미널에서 명령어를 실행할 수 있어야 합니다.

설치 과정 요약

save_docker_image.sh 스크립트 파일 준비
스크립트에 실행 권한 부여
스크립트 실행 (필요한 버전 정보 포함)
(필요시) Harbor 레지스트리 로그인 정보 입력
스크립트 완료 후 생성된 .tar 파일 확인

단계별 가이드

1. 스크립트 준비 및 실행 권한 부여

save_docker_image.sh 스크립트 파일을 작업하려는 디렉토리로 복사하거나 다운로드합니다.
터미널을 열고 스크립트 파일이 있는 디렉토리로 이동합니다.
다음 명령어를 실행하여 스크립트에 실행 권한을 부여합니다.
chmod +x save_docker_image.sh

2. 스크립트 실행

다음 형식으로 스크립트를 실행합니다. <version> 부분에는 다운로드하려는 QueryPie의 버전을 정확히 입력합니다.
./save_docker_image.sh <version>
예시: 10.2.6 버전을 다운로드하는 경우
./save_docker_image.sh 10.2.6

3. Harbor 레지스트리 로그인 처리

스크립트는 먼저 harbor.chequer.io 레지스트리에 로그인되어 있는지 확인합니다.

이미 로그인된 경우: 별도의 메시지 없이 다음 단계로 진행됩니다.
로그인되지 않은 경우: 다음과 같이 사용자명과 비밀번호를 입력하라는 프롬프트가 표시됩니다.
Not logged in to harbor.chequer.io Enter username: <여기에_Harbor_사용자명_입력> Enter password: <여기에_Harbor_비밀번호_입력>
⚠️ 주의: 비밀번호 입력 시 화면에 문자가 표시되지 않습니다. 정확하게 입력하고 Enter 키를 누르세요.

4. 이미지 다운로드 및 저장

로그인이 완료되면 스크립트는 다음 작업을 순차적으로 수행합니다.

기존 동일 버전 이미지 확인 및 삭제: 로컬 Docker 환경에 스크립트에서 지정한 버전과 동일한 QueryPie 및 QueryPie-Tools 이미지가 이미 존재하는 경우, 해당 이미지를 먼저 삭제합니다.
QueryPie 이미지 Pull: harbor.chequer.io/querypie/querypie:<version> 이미지를 Harbor 레지스트리에서 로컬로 다운로드(pull)합니다.
QueryPie 이미지 저장: 다운로드한 이미지를 querypie-{version}.tar 파일로 저장합니다.
QueryPie-Tools 이미지 Pull: harbor.chequer.io/querypie/querypie-tools:<version> 이미지를 Harbor 레지스트리에서 로컬로 다운로드(pull)합니다.
QueryPie-Tools 이미지 저장: 다운로드한 이미지를 querypie-tools-{version}.tar 파일로 저장합니다.

출력 결과

스크립트 실행이 성공적으로 완료되면 스크립트를 실행한 디렉토리에 다음과 같은 .tar 파일이 생성됩니다.

querypie-<version>.tar
querypie-tools-<version>.tar

📝 참고: 파일명 중복 처리
만약 동일한 이름의 .tar 파일이 이미 해당 디렉토리에 존재하는 경우, 스크립트는 자동으로 파일명 뒤에 번호를 붙여 중복을 방지합니다.

예시: querypie-10.2.6.tar 파일이 이미 존재하면, 새로 생성되는 파일은 querypie-10.2.6(1).tar 가 됩니다. 그 다음은 querypie-10.2.6(2).tar 순서로 생성됩니다. 이는 querypie-tools 이미지 파일에도 동일하게 적용됩니다.

문제해결

스크립트 실행 중 발생할 수 있는 일반적인 문제와 해결 방법입니다.

오류: bash: ./save_docker_image.sh: Permission denied
- 원인: 스크립트 파일에 실행 권한이 없습니다.
- 해결책: chmod +x save_docker_image.sh 명령어를 실행하여 권한을 부여하세요.
오류: docker: command not found
- 원인: Docker가 설치되지 않았거나, 현재 사용자의 PATH 환경 변수에 Docker 실행 파일 경로가 포함되지 않았습니다.
- 해결책: Docker를 설치하거나, Docker 설치 경로를 확인하고 PATH 환경 변수에 추가하세요. Docker 데몬이 실행 중인지 확인하세요 (systemctl status docker 또는 service docker status).
오류: Harbor 로그인 실패 (Error response from daemon: Get <https://harbor.chequer.io/v2/:> unauthorized: authentication required 또는 유사 메시지)
- 원인: 잘못된 사용자명 또는 비밀번호를 입력했거나, 해당 계정에 Harbor 레지스트리 접근 권한이 없습니다.
- 해결책: 정확한 사용자명과 비밀번호를 다시 입력하세요. 필요한 경우, Harbor 관리자에게 문의하여 계정 권한을 확인하세요.
오류: 디스크 공간 부족 (no space left on device)
- 원인: Docker 이미지를 다운로드하거나 .tar 파일로 저장할 디스크 공간이 부족합니다.
- 해결책: 불필요한 파일을 삭제하거나 Docker 시스템 정리(docker system prune -a)를 통해 디스크 공간을 확보하세요. 또는 더 많은 공간이 있는 다른 파티션이나 디스크에서 스크립트를 실행하세요.
오류: 이미지 Pull 실패 (네트워크 관련)
- 원인: 네트워크 연결이 불안정하거나 방화벽 설정으로 인해 Harbor 레지스트리 접근이 차단되었을 수 있습니다.
- 해결책: 인터넷 연결 상태를 확인하고, 필요한 경우 네트워크 관리자에게 문의하여 harbor.chequer.io (및 필요한 포트)에 대한 접근이 허용되는지 확인하세요.

최종 확인 사항

스크립트 실행 후 다음 사항을 확인하여 모든 과정이 정상적으로 완료되었는지 점검합니다.

[ ] 터미널에 오류 메시지 없이 스크립트 실행이 완료되었는가?
[ ] 스크립트를 실행한 디렉토리에 querypie-<version>.tar 파일이 생성되었는가?
[ ] 스크립트를 실행한 디렉토리에 querypie-tools-<version>.tar 파일이 생성되었는가?
[ ] 생성된 .tar 파일의 크기가 비정상적으로 작지 않은가? (일반적으로 수백 MB ~ 몇 GB 크기)

주의: 이 가이드에 포함된 명령어와 설정은 일반적인 환경을 기준으로 작성되었습니다. 실제 적용 시에는 사용자 본인의 환경에 맞춰 충분히 테스트하고 검증한 후 진행하시기 바랍니다.