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을 열고 다음을 실행하세요.

   wsl --install -d Ubuntu
   

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

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

   wsl --update
   wsl --version
   wsl --list --verbose
   

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

   wsl --set-version Ubuntu 2
   

   Docker에는 WSL 2.1.5 이상이 필요합니다. wsl --version으로 확인하는 WSL 소프트웨어 버전과 배포판의 VERSION 2 열은 서로 다른 확인 항목입니다. 설치에 실패하면 설치 문제 해결과 Microsoft의 설치 안내를 참조하고, WSL에서 가상화를 사용할 수 없다고 보고하면 BIOS/UEFI에서 하드웨어 가상화를 활성화하세요.

2. Docker Desktop 설치 및 시작

   프로세서에 맞는 Docker Desktop for Windows를 다운로드하고 설치 프로그램을 실행하세요. 선택지가 있다면 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 백엔드 가이드를 참조하세요.

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

3. Ubuntu에서 Docker 확인

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

   docker version
   docker compose version
   docker ps
   

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

   docker를 사용할 수 없거나 연결할 수 없다면 WSL Integration을 적용한 후 Ubuntu를 다시 열고 Docker Desktop이 실행 중인지 확인하세요. 문제 해결을 참조하세요.

4. 리소스 및 Docker 소켓 확인

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

   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 설정을 통해 리소스 한도를 관리합니다. wsl --shutdown이 필요한 변경은 실행 중인 모든 WSL 배포판과 Docker 워크로드를 중단시키므로, 인스턴스를 시작하기 전에 적용하세요.

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

​

다음 단계

Ubuntu에서 docker ps가 작동하면 1. Toolkit 다운로드로 계속 진행하세요.