0. Cài đặt WSL 2 và Docker Desktop

Cài đặt WSL 2 và Ubuntu, sau đó kết nối Ubuntu với Docker Desktop trên Windows.

Ayakaleaf Pro sử dụng các container Linux. Trên Windows, hãy cài đặt Docker Desktop với backend WSL 2 và chạy các script của Toolkit trong Ubuntu.

WSL 2 cung cấp kernel Linux. Docker Desktop quản lý Docker engine trong môi trường docker-desktop riêng của nó; việc bật WSL Integration cho phép Docker CLI trong Ubuntu giao tiếp với engine đó. Sau đó Toolkit khởi động ứng dụng, MongoDB và Redis dưới dạng các container. Khi bật sandboxed compiles, ứng dụng sử dụng Docker socket của engine để khởi động một container TeX Live riêng cho mỗi lần biên dịch. Bạn không cần cài đặt MongoDB, Redis hay TeX Live trên Windows.

1. Cài đặt WSL 2 và Ubuntu

   Mở PowerShell với quyền quản trị viên trong Windows và chạy:

   wsl --install -d Ubuntu
   

   Khởi động lại Windows nếu được yêu cầu. Mở Ubuntu từ menu Start và tạo tên người dùng và mật khẩu Linux. Đây là tài khoản dùng cho sudo bên trong Ubuntu; nó tách biệt với thông tin đăng nhập Windows của bạn.

   Quay lại PowerShell, cập nhật WSL và kiểm tra bản phân phối:

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

   Hàng Ubuntu phải hiển thị VERSION 2. Nếu nó hiển thị 1, hãy dùng chính xác tên bản phân phối từ danh sách:

   wsl --set-version Ubuntu 2
   

   Docker yêu cầu WSL 2.1.5 trở lên; phiên bản phần mềm WSL từ wsl --version và cột VERSION 2 của bản phân phối là hai bước kiểm tra khác nhau. Xem khắc phục sự cố cài đặt và hướng dẫn cài đặt của Microsoft nếu cài đặt thất bại, và bật ảo hóa phần cứng trong BIOS/UEFI nếu WSL báo rằng nó không khả dụng.

2. Cài đặt và khởi động Docker Desktop

   Tải xuống Docker Desktop for Windows cho bộ xử lý của bạn và chạy trình cài đặt. Hãy dùng backend WSL 2 nếu được cung cấp. Mở Docker Desktop từ menu Start của Windows và đợi engine khởi động.

   Trong Settings → General của Docker Desktop, bật Use WSL 2 based engine nếu tùy chọn này được hiển thị. Trong Settings → Resources → WSL Integration, bật tích hợp cho Ubuntu, sau đó chọn Apply hoặc Apply & restart. Nếu Ubuntu không phải là bản phân phối mặc định của bạn, hãy bật rõ ràng công tắc riêng của nó.

   Nếu không thấy WSL Integration, hãy kiểm tra rằng Docker Desktop đang dùng Linux containers. Xem hướng dẫn backend WSL 2 của Docker.

   Hãy dùng tích hợp của Docker Desktop cho hướng dẫn này. Việc cài đặt một Docker Engine thứ hai bằng apt install docker.io hoặc khởi động dockerd bên trong Ubuntu sẽ tạo ra một thiết lập riêng biệt và có thể gây xung đột. Nếu bạn đã dùng một Engine trong Ubuntu, hãy làm theo hướng dẫn di chuyển của Docker trước khi chuyển đổi; giữ lại dữ liệu ứng dụng và các bản sao lưu hiện có.

3. Kiểm tra Docker từ Ubuntu

   Mở một terminal Ubuntu. Chạy các lệnh sau ở đó, không dùng sudo:

   docker version
   docker compose version
   docker ps
   

   docker version phải hiển thị cả Client và Server. Danh sách container trống là bình thường trên một bản cài đặt mới. Chỉ riêng docker --version không chứng minh rằng engine đang chạy.

   Nếu docker không khả dụng hoặc không thể kết nối, hãy mở lại Ubuntu sau khi áp dụng WSL Integration và kiểm tra rằng Docker Desktop đang chạy. Xem Khắc phục sự cố.

4. Kiểm tra tài nguyên và Docker socket

   Kiểm tra các tài nguyên mà Docker nhìn thấy:

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

   Đối với một phiên bản cục bộ nhỏ, 4 CPU và 8 GB bộ nhớ khả dụng cho Docker là gợi ý khởi đầu, không phải mức tối thiểu đã được đo lường. Hãy giữ đủ bộ nhớ cho cả Windows. Với backend WSL 2, giới hạn tài nguyên được quản lý thông qua thiết lập WSL, thay vì các thanh trượt tài nguyên của Docker Desktop như trên Mac. Những thay đổi yêu cầu wsl --shutdown sẽ làm gián đoạn tất cả các bản phân phối WSL và workload Docker đang chạy; hãy áp dụng chúng trước khi khởi động phiên bản.

   Hãy giữ DOCKER_SOCKET_PATH=/var/run/docker.sock trong cấu hình Toolkit. Ứng dụng cần socket engine này cho sandboxed compiles. Không đổi quyền của nó thành 777 để sửa lỗi kết nối; thay vào đó, hãy khôi phục tích hợp của Docker Desktop.

​

Bước tiếp theo

Khi docker ps hoạt động trong Ubuntu, hãy tiếp tục với 1. Tải xuống Toolkit.