도커(docker)에 Qdrant 벡터 데이터베이스 실행하기(로컬 & 클라우드)

아래 Docker 명령어는 Qdrant 벡터 데이터베이스를 Docker 컨테이너로 실행하는 데 사용됩니다.

docker run -p 6333:6333 -p 6334:6334 -v "$(pwd)/qdrant_storage:/qdrant/storage:z" qdrant/qdrant

이 명령어는 Qdrant 이미지를 사용하여 새로운 Docker 컨테이너를 생성하고 실행하는 명령입니다.

 

1. docker run

• docker run: Docker 이미지를 기반으로 새로운 컨테이너를 생성하고 실행하는 기본 명령어입니다.

2. -p 6333:6333

• -p: 포트 매핑 (Port Mapping) 옵션입니다. 호스트(당신의 컴퓨터)의 포트와 컨테이너 내부의 포트를 연결해 줍니다.
• 6333:6333:
  • 첫 번째 6333: 호스트 컴퓨터의 포트 번호입니다.
  • 두 번째 6333: 컨테이너 내부에서 Qdrant가 사용하는 기본 gRPC 포트 번호입니다.
  • 의미: 이 설정은 호스트 컴퓨터의 6333번 포트로 들어오는 모든 네트워크 요청을 Qdrant 컨테이너 내부의 6333번 포트로 전달하라는 의미입니다. Qdrant 클라이언트(Python 코드 등)가 Qdrant 서버와 통신할 때 이 포트를 사용합니다.

3. -p 6334:6334

• -p: 역시 포트 매핑 옵션입니다.
• 6334:6334:
  • 첫 번째 6334: 호스트 컴퓨터의 포트 번호입니다.
  • 두 번째 6334: 컨테이너 내부에서 Qdrant가 사용하는 기본 REST API 포트 번호입니다.
  • 의미: 이 설정은 호스트 컴퓨터의 6334번 포트로 들어오는 모든 네트워크 요청을 Qdrant 컨테이너 내부의 6334번 포트로 전달하라는 의미입니다. Qdrant의 웹 UI나 RESTful API를 통해 Qdrant 서버와 통신할 때 이 포트를 사용합니다.

4. -v "$(pwd)/qdrant_storage:/qdrant/storage:z"

• -v: 볼륨 마운트 (Volume Mount) 옵션입니다. 호스트 컴퓨터의 특정 디렉토리를 컨테이너 내부의 특정 디렉토리와 연결하여 데이터를 영구적으로 저장할 수 있게 해줍니다. 컨테이너가 삭제되더라도 데이터는 호스트에 남아있게 됩니다.
• "$(pwd)/qdrant_storage":
  • $(pwd): 현재 명령어를 실행하는 터미널의 현재 작업 디렉토리(Current Working Directory)를 의미합니다. 예를 들어, C:\user\user에서 이 명령어를 실행했다면, 이 경로는 C:\user\user\qdrant_storage가 됩니다.
  • /qdrant/storage: 컨테이너 내부에서 Qdrant가 데이터를 저장하는 기본 경로입니다.
  • 의미: 이 설정은 호스트 컴퓨터의 현재 디렉토리 아래에 있는 qdrant_storage라는 폴더를 Qdrant 컨테이너 내부의 /qdrant/storage 경로에 연결하라는 의미입니다. Qdrant가 생성하는 모든 데이터(컬렉션, 벡터, 페이로드 등)는 컨테이너 내부의 /qdrant/storage에 저장되며, 이는 실제로는 호스트의 qdrant_storage 폴더에 저장됩니다. 이렇게 하면 컨테이너를 중지하거나 삭제해도 Qdrant 데이터는 손실되지 않고 유지됩니다.
• :z: SELinux 컨텍스트 레이블링 옵션입니다. (주로 Linux 시스템에서 사용되며, Windows나 macOS에서는 큰 의미가 없을 수 있습니다.)
  • 의미: 컨테이너가 호스트 볼륨을 읽고 쓸 수 있도록 SELinux 보안 정책을 자동으로 조정해 줍니다. z 옵션은 볼륨을 공유하는 모든 컨테이너가 해당 볼륨에 접근할 수 있도록 허용합니다.

5. qdrant/qdrant

• qdrant/qdrant: 실행할 Docker 이미지의 이름입니다.
  • qdrant: Docker Hub의 사용자/조직 이름입니다.
  • qdrant: 이미지의 레포지토리 이름입니다.
  • 의미: Docker Hub에서 qdrant/qdrant라는 이름의 최신 Qdrant 이미지를 다운로드하여 컨테이너를 실행하라는 의미입니다. (만약 로컬에 이미지가 없다면 자동으로 다운로드합니다.)

명령어 전체 요약

이 명령어는 "현재 디렉토리에 qdrant_storage라는 폴더를 만들고, 이 폴더를 Qdrant 컨테이너의 데이터 저장 공간으로 사용하면서, 호스트의 6333번 포트와 6334번 포트를 각각 컨테이너의 gRPC 및 REST API 포트에 연결하여 Qdrant 서버를 실행하라"는 의미입니다. 이 명령어를 통해 Qdrant 서버를 안정적으로 실행하고, 컨테이너가 재시작되거나 삭제되어도 데이터가 보존되도록 설정할 수 있습니다.

 

AWS

sudo docker run -p 6333:6333 -p 6334:6334 -v "$(pwd)/qdrant_storage:/qdrant/storage:z" qdrant/qdrant 

 

AWS 인스턴스에서 실행할 때 추가되는 부분은 sudo와 네트워크 설정에 대한 고려사항입니다.

1. sudo:
   • sudo는 "superuser do"의 약자로, 일반 사용자가 관리자(root) 권한으로 명령을 실행할 수 있도록 해주는 명령어입니다.
   • AWS 인스턴스(대부분 Linux 기반)에서 Docker를 설치하고 실행할 때, 기본적으로 Docker 명령은 root 권한으로 실행되어야 합니다. 따라서 docker 명령 앞에 sudo를 붙여서 관리자 권한으로 실행하는 것이 일반적입니다.
   • 만약 sudo 없이 Docker 명령을 실행하고 싶다면, 현재 사용자 계정을 docker 그룹에 추가해야 합니다. (예: sudo usermod -aG docker $USER 후 재로그인) 하지만 sudo를 사용하는 것이 더 간단하고 흔한 방법입니다.
2. AWS 인스턴스 환경 고려사항:
   • 보안 그룹 (Security Group): AWS 인스턴스에서 Qdrant에 외부에서 접속하려면, 해당 인스턴스에 연결된 보안 그룹에서 6333번 (gRPC) 포트와 6334번 (REST API) 포트에 대한 인바운드(Inbound) 규칙을 열어주어야 합니다.
     • 일반적으로 개발/테스트 목적이라면 특정 IP 주소(예: 본인 사무실/집 IP)나 0.0.0.0/0 (모든 IP 허용 - 보안에 취약하므로 주의)으로 설정할 수 있습니다.
     • 실제 서비스 환경에서는 특정 서버의 IP 주소만 허용하는 등 보안을 강화해야 합니다.
   • $(pwd): AWS 인스턴스에서도 $(pwd)는 명령어를 실행하는 현재 디렉토리를 의미합니다. 따라서 Qdrant 데이터가 저장될 qdrant_storage 폴더는 인스턴스 내에서 명령어를 실행한 위치에 생성됩니다.
   • 퍼블릭 IP / DNS: Qdrant 클라이언트(예: 로컬 PC의 Python 코드)에서 AWS 인스턴스의 Qdrant 서버에 접속하려면, host="localhost" 대신 AWS 인스턴스의 퍼블릭 IP 주소나 퍼블릭 DNS 이름을 사용해야 합니다.

결론적으로, docker run 명령어의 각 옵션(-p, -v, 이미지 이름)에 대한 설명은 AWS 인스턴스 환경에서도 동일하게 적용됩니다. 단지 Linux 환경에서 Docker를 실행하기 위해 sudo를 붙이며, AWS의 네트워크 보안 설정인 보안 그룹을 통해 해당 포트들을 열어주어야 외부에서 Qdrant 서버에 접근할 수 있다는 점만 추가로 고려하시면 됩니다.