> ## Documentation Index > Fetch the complete documentation index at: https://docs.baeum.ai.kr/llms.txt > Use this file to discover all available pages before exploring further. # Rancher Desktop 설치 가이드 ## Rancher Desktop이란? Rancher Desktop은 Windows에서 Docker 컨테이너를 쉽게 실행하고 관리할 수 있게 해주는 무료 프로그램입니다. Docker Desktop의 무료 대안으로, 개발 환경에서 컨테이너 기반 애플리케이션을 만들고 테스트할 때 사용합니다. **Docker란?** 프로그램을 "컨테이너"라는 독립된 환경에 담아서 실행하는 기술입니다. 컨테이너를 사용하면 내 컴퓨터 환경에 관계없이 누구나 동일한 환경에서 프로그램을 실행할 수 있습니다. ## 사전 요구사항 설치를 시작하기 전에 다음 조건을 확인합니다. | 항목 | 요구사항 | | ---- | ------------------------------------------------------------ | | 운영체제 | Windows 10 이상 (64비트) | | WSL2 | 필수 - 아직 설치하지 않았다면 [WSL 설치 가이드](/setup/windows/wsl)를 먼저 진행합니다 | | 권한 | 컴퓨터 관리자 권한 | WSL2가 설치되어 있지 않으면 Rancher Desktop 설치 도중 경고가 뜨고 진행이 안 됩니다. 반드시 WSL2를 먼저 설치합니다. ## 다운로드 웹 브라우저에서 [Rancher Desktop 공식 웹사이트](https://rancherdesktop.io/)에 접속합니다. Rancher Desktop 공식 웹사이트 웹사이트 상단에 운영체제별 다운로드 버튼이 보입니다. **Download for Windows (x64)** 버튼을 클릭하여 `.exe` 설치 파일을 다운로드합니다. 파일 크기는 약 300\~400MB 정도입니다. 다운로드 버튼이 여러 개 보인다면 **Windows (x64)** 라고 적힌 것을 선택합니다. macOS나 Linux용이 아닌지 확인합니다. ## 설치 다운로드한 `.exe` 파일을 더블클릭하여 실행합니다. 아래와 같이 "Welcome to the Rancher Desktop Setup Wizard" 화면이 나타납니다. 설치 마법사 시작 화면 이 화면은 설치 준비가 되었다는 의미입니다. **Next** 버튼을 클릭하여 다음 단계로 넘어가세요. 설치가 중간에 중단되면 아래와 같은 화면이 나타납니다. **Finish** 버튼을 누르고 설치 파일을 다시 실행하면 됩니다. 설치 중단 화면 Apache License 2.0 라이선스 계약 내용이 표시됩니다. 이것은 Rancher Desktop이 무료 오픈소스 소프트웨어라는 것을 알려주는 약관입니다. 라이선스 동의 전 - 체크박스가 비어있는 상태 화면 하단의 **"I accept the terms in the License Agreement"** (라이선스 약관에 동의합니다) 체크박스를 클릭합니다. 체크박스에 체크 표시가 나타나면 **Next** 버튼이 활성화됩니다. 라이선스 동의 완료 - 체크박스에 체크된 상태 체크 표시를 확인한 후 **Next** 버튼을 클릭합니다. 만약 컴퓨터에 WSL2가 설치되어 있지 않으면, 아래와 같은 경고 메시지가 나타납니다. WSL2가 필요하다는 경고 메시지 이 메시지가 나타났다면 다음과 같이 진행합니다: 1. **OK** 버튼을 눌러 경고를 닫습니다 2. Rancher Desktop 설치를 취소합니다 3. [WSL 설치 가이드](/setup/windows/wsl)를 따라 WSL2를 먼저 설치합니다 4. 컴퓨터를 재시작한 후 Rancher Desktop 설치를 다시 진행합니다 WSL2 없이는 Rancher Desktop이 정상적으로 동작하지 않습니다. 반드시 WSL2를 먼저 설치합니다. 누구를 위해 설치할지 선택하는 화면입니다. 설치 범위 선택 화면 두 가지 선택지가 있습니다: * **Install for all users of this machine** (이 컴퓨터의 모든 사용자): 컴퓨터를 여러 사람이 함께 사용하는 경우 선택합니다. 관리자 권한이 필요합니다. * **Install just for you (사용자이름)** (나만 사용): 혼자 사용하는 컴퓨터라면 이 옵션을 선택합니다. 관리자 권한이 필요 없습니다. 개인 컴퓨터라면 어떤 것을 선택해도 괜찮지만, **Install for all users of this machine**을 선택하면 네트워크 포트 관련 기능이 더 잘 동작합니다. 원하는 옵션을 선택한 후 **Next** 버튼을 클릭합니다. 모든 설정이 완료되었습니다. 아래 화면에서 **Install** 버튼을 클릭하면 실제 설치가 시작됩니다. 설치 준비 완료 화면 * **Install**: 설치를 시작합니다 * **Back**: 이전 단계로 돌아가 설정을 변경할 수 있습니다 * **Cancel**: 설치를 취소합니다 **Install** 버튼을 클릭합니다. 설치가 진행됩니다. 진행 상황이 화면에 표시되며, 중간에 "Configuring Windows Firewall"(Windows 방화벽 설정 중)이라는 상태가 보일 수 있습니다. 설치 진행 중 - Windows 방화벽 설정 이 과정은 Rancher Desktop이 네트워크를 사용할 수 있도록 Windows 방화벽에 허용 규칙을 추가하는 것입니다. 자동으로 진행됩니다. 설치가 진행되는 동안 컴퓨터를 끄거나 설치 창을 닫지 마세요. 보통 1\~3분 정도 소요됩니다. 설치가 완료되면 아래와 같은 화면이 나타납니다. 설치 완료 화면 * **Run Rancher Desktop** 체크박스: 체크하면 Finish를 누른 후 바로 Rancher Desktop이 실행됩니다 * **Finish** 버튼을 클릭하여 설치 마법사를 종료합니다 ## 초기 설정 (처음 실행 시) Rancher Desktop을 처음 실행하면 아래와 같은 초기 설정 화면이 나타납니다. 초기 설정 화면 - Kubernetes 활성화, dockerd(moby) 선택 설정해야 할 항목이 3가지 있습니다: **1. Enable Kubernetes (쿠버네티스 활성화)** * Kubernetes는 여러 컨테이너를 자동으로 관리해주는 시스템입니다 * Docker만 사용할 예정이라면 **체크를 해제**합니다 (아래 그림 참고) * Kubernetes가 필요한 경우에만 체크 상태로 두세요 **2. Kubernetes Version (쿠버네티스 버전)** * Kubernetes를 활성화한 경우에만 의미가 있습니다. 기본값을 그대로 사용하면 됩니다. **3. Container Engine (컨테이너 엔진)** * **dockerd (moby)**: `docker` 명령어를 사용할 수 있습니다. **대부분의 경우 이것을 선택합니다.** * **containerd**: `nerdctl` 명령어를 사용합니다. 특별한 이유가 없다면 선택하지 않아도 됩니다. Docker만 사용할 목적이라면 Kubernetes를 비활성화합니다. Kubernetes를 끄면 컴퓨터의 메모리와 CPU를 절약할 수 있습니다. 초기 설정 화면 - Kubernetes 비활성화 위 그림은 Kubernetes를 비활성화하고 dockerd(moby)를 선택한 상태입니다. 설정이 완료되면 **OK** 버튼을 클릭합니다. OK 버튼을 누르면 Rancher Desktop이 내부적으로 WSL에 리눅스 환경을 등록합니다. 화면 하단 상태 표시줄에 "Registering WSL distribution"이라는 메시지가 보입니다. 메인 화면 - WSL distribution 등록 진행 중 이 과정은 자동으로 진행되며 보통 1\~2분 정도 소요됩니다. 모든 설정이 완료되면 Rancher Desktop 메인 화면이 나타납니다. Rancher Desktop 메인 화면 왼쪽 메뉴에서 다양한 기능을 확인할 수 있습니다: * **General**: 버전 정보, 업데이트 설정 * **Containers**: 실행 중인 컨테이너 목록 * **Images**: 다운로드된 컨테이너 이미지 목록 * **Preferences** (왼쪽 하단): 컨테이너 엔진, Kubernetes 등 설정 변경 화면 하단 상태 표시줄에서 현재 상태를 확인할 수 있습니다: * **Network status: online** - 네트워크 연결 정상 * **Kubernetes: deactivated** - Kubernetes 비활성화 상태 (비활성화한 경우) * **CE: moby** - 컨테이너 엔진으로 dockerd(moby) 사용 중 ## 설치 확인 설치가 제대로 되었는지 확인합니다. PowerShell 또는 명령 프롬프트를 열어 다음 명령어를 실행합니다. ### Docker 동작 확인 ```bash theme={null} docker --version ``` 버전 정보가 정상적으로 출력되면 Docker가 잘 설치된 것입니다. ```bash theme={null} docker run hello-world ``` "Hello from Docker!" 메시지가 출력되면 Docker 컨테이너가 정상적으로 실행되는 것입니다. ### Kubernetes 확인 (활성화한 경우에만) Kubernetes를 활성화한 경우에만 아래 명령어를 실행합니다: ```bash theme={null} kubectl version kubectl get nodes ``` ## 문제 해결 * **`docker` 명령어가 인식되지 않는 경우**: Rancher Desktop이 실행 중인지 확인합니다. 시스템 트레이(화면 오른쪽 하단)에 Rancher Desktop 아이콘이 있어야 합니다. * **WSL2 관련 오류가 나는 경우**: PowerShell을 관리자 권한으로 열고 `wsl --update` 명령어를 실행합니다. * **컨테이너가 실행되지 않는 경우**: Rancher Desktop을 종료했다가 다시 시작해 봅니다. ## 설치 점검 목록 * 관리자 권한/필수 도구 등 사전 요구사항을 먼저 확인했습니다. * 설치 후 버전 확인 명령어(`--version`)를 실행해 정상 설치를 검증했습니다. * PATH/환경변수 변경이 필요한 경우 터미널을 다시 열어 적용 여부를 확인했습니다. * 문제가 생겼을 때를 대비해 설치 로그 또는 스크린샷을 남겼습니다. ## 관련 문서 운영체제별 설치 흐름을 다시 확인합니다. 다음 설치 단계를 이어서 진행합니다.