Windows 환경에서 Docker 설치 가이드

Microsoft Store에서 원하는 Linux 배포판(예: Ubuntu)을 설치할 수 있습니다. 또는 PowerShell에서 직접 설치할 수도 있습니다:

이 명령어는 Ubuntu를 다운로드하고 설치합니다. 설치 후 사용자 이름과 비밀번호를 설정하라는 메시지가 표시됩니다.

터미널에서 Docker 테스트

PowerShell 또는 명령 프롬프트를 열고 다음 명령어를 실행합니다:

Docker 버전 확인:

예상 출력: Docker version 24.0.2, build cb74dfc (버전은 다를 수 있음)

Docker 시스템 정보 확인:

Hello World 컨테이너 실행:

이 명령어는 Docker Hub에서 hello-world 이미지를 다운로드하고 컨테이너를 실행합니다. 성공적으로 실행되면 환영 메시지가 표시됩니다.

WSL 2에서 Docker 테스트

WSL 2 터미널에서도 Docker 명령어가 작동하는지 확인해 보세요:

1. 시작 메뉴에서 "Ubuntu"를 검색하여 WSL 터미널을 실행합니다.
2. 다음 명령어를 실행합니다:

이 명령어는 Ubuntu 컨테이너를 실행하고 bash 셸을 제공합니다. exit 명령으로 컨테이너를 종료할 수 있습니다.

기본 Qdrant 컨테이너 실행

다음 명령어로 Qdrant 컨테이너를 실행합니다:

이 명령어는 Qdrant 이미지를 다운로드하고 6333, 6334 포트를 호스트에 매핑하여 컨테이너를 시작합니다.

데이터 지속성을 위한 볼륨 마운트

Qdrant 데이터를 호스트 시스템에 저장하려면 볼륨을 마운트합니다:

컨테이너 백그라운드에서 실행

Qdrant 컨테이너를 백그라운드에서 실행하려면:

Qdrant 컨테이너 설정 구성

사용자 정의 설정 파일로 Qdrant를 실행하려면:

1. 로컬 시스템에 config.yaml 파일을 생성합니다.
2. 다음 명령어로 컨테이너를 실행합니다:

PowerShell에서는 $(pwd) 대신 ${PWD}를 사용합니다:

Qdrant가 제대로 실행되고 있는지 확인하려면 웹 브라우저에서 다음 URL로 접속합니다:

http://localhost:6333/dashboard

또는 API를 통해 상태를 확인할 수 있습니다:

예상 응답:

{
  "title": "Qdrant - Vector Search Engine",
  "version": "1.x.x"
}

Docker Desktop이 시작되지 않는 경우

1. WSL 2가 올바르게 설치되어 있는지 확인합니다: wsl -l -v
2. 하드웨어 가상화가 활성화되어 있는지 확인합니다.
3. Windows 업데이트가 최신 상태인지 확인합니다.
4. Docker Desktop을 재설치합니다.

WSL 2 오류 메시지가 표시되는 경우

1. Linux 커널 업데이트 패키지를 다시 설치합니다.
2. 다음 명령어로 WSL을 업데이트합니다: wsl --update

포트 충돌 문제

Qdrant 포트(6333, 6334)가 이미 사용 중인 경우:

1. 사용 중인 포트를 확인합니다: netstat -ano | findstr 6333
2. 다른 포트를 사용하여 Qdrant를 실행합니다: docker run -p 7333:6333 -p 7334:6334 qdrant/qdrant

Docker 컨테이너가 정상적으로 종료되지 않는 경우

1. 실행 중인 컨테이너 목록 확인: docker ps -a
2. 강제 종료: docker rm -f 컨테이너ID

WSL 2 메모리 사용량이 높은 경우

WSL 2가 시스템 메모리를 너무 많이 사용하는 경우, 다음과 같이 메모리 제한을 설정할 수 있습니다:

1. 사용자 홈 디렉토리에 .wslconfig 파일을 생성합니다.
2. 다음 내용을 추가합니다:

[wsl2]
memory=4GB
processors=2

WSL을 재시작합니다: wsl --shutdown

Docker 명령어가 작동하지 않는 경우

1. Docker Desktop이 실행 중인지 확인합니다.
2. Docker 서비스를 재시작합니다: Restart-Service *docker*
3. 시스템을 재부팅합니다.