> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 0. WSL 2 및 Docker Desktop 설정

> WSL 2와 Ubuntu를 설치한 다음 Windows에서 Ubuntu를 Docker Desktop에 연결합니다.

Ayakaleaf Pro는 Linux 컨테이너를 사용합니다. Windows에서는 WSL 2 백엔드와 함께 Docker Desktop을 설치하고 Toolkit 스크립트를 Ubuntu에서 실행합니다.

WSL 2는 Linux 커널을 제공합니다. Docker Desktop은 자체 `docker-desktop` 환경에서 Docker 엔진을 관리하며, **WSL Integration**을 활성화하면 Ubuntu의 Docker CLI가 해당 엔진과 통신할 수 있습니다. 그런 다음 Toolkit이 애플리케이션, MongoDB, Redis를 컨테이너로 시작합니다. Sandboxed Compiles를 활성화하면 애플리케이션은 엔진의 Docker 소켓을 사용하여 컴파일마다 별도의 TeX Live 컨테이너를 시작합니다. Windows용 MongoDB, Redis 또는 TeX Live를 설치할 필요는 없습니다.

**1. WSL 2 및 Ubuntu 설치**

Windows에서 **관리자 권한으로 PowerShell**을 열고 다음을 실행하세요.

```powershell theme={null}
wsl --install -d Ubuntu
```

메시지가 표시되면 Windows를 다시 시작하세요. 시작 메뉴에서 **Ubuntu**를 열고 Linux 사용자 이름과 비밀번호를 만드세요. 이는 Ubuntu 내부에서 `sudo`에 사용하는 계정이며, Windows 로그인과는 별개입니다.

**PowerShell**로 돌아가 WSL을 업데이트하고 배포판을 확인하세요.

```powershell theme={null}
wsl --update
wsl --version
wsl --list --verbose
```

Ubuntu 행에 **VERSION 2**가 표시되어야 합니다. 1로 표시되면 목록에 나온 정확한 배포판 이름을 사용하세요.

```powershell theme={null}
wsl --set-version Ubuntu 2
```

Docker에는 WSL **2.1.5 이상**이 필요합니다. `wsl --version`으로 확인하는 WSL 소프트웨어 버전과 배포판의 **VERSION 2** 열은 서로 다른 확인 항목입니다. 설치에 실패하면 [설치 문제 해결](https://ayakaleaf-pro.mintlify.site/ko/on-premises/installation/using-docker-compose/windows/troubleshooting.md#wsl-or-docker-reports-that-virtualization-is-unavailable)과 [Microsoft의 설치 안내](https://learn.microsoft.com/en-us/windows/wsl/install)를 참조하고, WSL에서 가상화를 사용할 수 없다고 보고하면 BIOS/UEFI에서 하드웨어 가상화를 활성화하세요.

**2. Docker Desktop 설치 및 시작**

프로세서에 맞는 [Docker Desktop for Windows](https://docs.docker.com/desktop/setup/install/windows-install/)를 다운로드하고 설치 프로그램을 실행하세요. 선택지가 있다면 **WSL 2** 백엔드를 사용하세요. Windows 시작 메뉴에서 **Docker Desktop**을 열고 엔진이 시작될 때까지 기다리세요.

Docker Desktop **Settings → General**에서 **Use WSL 2 based engine** 옵션이 표시되면 활성화하세요. **Settings → Resources → WSL Integration**에서 **Ubuntu**에 대한 통합을 활성화한 다음 **Apply** 또는 **Apply & restart**를 선택하세요. Ubuntu가 기본 배포판이 아니라면 해당 스위치를 명시적으로 켜세요.

WSL Integration이 보이지 않으면 Docker Desktop이 **Linux containers**를 사용하고 있는지 확인하세요. [Docker의 WSL 2 백엔드 가이드](https://docs.docker.com/desktop/features/wsl/)를 참조하세요.

이 가이드에서는 Docker Desktop의 통합을 사용하세요. Ubuntu 안에서 `apt install docker.io`로 두 번째 Docker Engine을 설치하거나 `dockerd`를 시작하면 별도의 설정이 만들어져 충돌이 발생할 수 있습니다. 이미 Ubuntu에서 Engine을 사용하고 있다면 전환하기 전에 Docker의 마이그레이션 안내를 따르고, 기존 애플리케이션 데이터와 백업을 유지하세요.

**3. Ubuntu에서 Docker 확인**

**Ubuntu** 터미널을 여세요. 그곳에서 `sudo` 없이 다음 명령을 실행하세요.

```bash theme={null}
docker version
docker compose version
docker ps
```

`docker version`에는 **Client**와 **Server**가 모두 표시되어야 합니다. 새 설치에서는 컨테이너 목록이 비어 있는 것이 정상입니다. `docker --version`만으로는 엔진이 실행 중이라는 것이 증명되지 않습니다.

`docker`를 사용할 수 없거나 연결할 수 없다면 WSL Integration을 적용한 후 Ubuntu를 다시 열고 Docker Desktop이 실행 중인지 확인하세요. [문제 해결](https://ayakaleaf-pro.mintlify.site/ko/on-premises/installation/using-docker-compose/windows/troubleshooting.md#docker-is-unavailable-in-ubuntu)을 참조하세요.

**4. 리소스 및 Docker 소켓 확인**

Docker에서 보이는 리소스를 확인하세요.

```bash theme={null}
docker info --format 'CPUs={{.NCPU}} Memory={{.MemTotal}} Kernel={{.KernelVersion}}'
df -h "$HOME"
ls -l /var/run/docker.sock
```

소규모 로컬 인스턴스라면 Docker에서 사용할 수 있는 CPU 4개와 메모리 8 GB가 권장 시작점이며, 측정된 최소 요구 사항이 아닙니다. Windows를 위한 메모리도 충분히 남겨 두세요. WSL 2 백엔드에서는 Mac의 Docker Desktop 리소스 슬라이더가 아니라 [WSL 설정](https://learn.microsoft.com/en-us/windows/wsl/wsl-config)을 통해 리소스 한도를 관리합니다. `wsl --shutdown`이 필요한 변경은 실행 중인 모든 WSL 배포판과 Docker 워크로드를 중단시키므로, 인스턴스를 시작하기 전에 적용하세요.

Toolkit 구성에서 `DOCKER_SOCKET_PATH=/var/run/docker.sock`을 그대로 두세요. 애플리케이션은 Sandboxed Compiles를 위해 이 엔진 소켓이 필요합니다. 연결 오류를 해결하기 위해 권한을 `777`로 변경하지 말고, 대신 Docker Desktop의 통합을 복원하세요.

### 다음 단계

Ubuntu에서 `docker ps`가 작동하면 [1. Toolkit 다운로드](https://ayakaleaf-pro.mintlify.site/ko/on-premises/installation/using-docker-compose/windows/1.-download-the-toolkit.md)로 계속 진행하세요.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.