# 樂達APP安裝教學

本說明文件涵蓋 **Docker Desktop 安裝**、**WSL 2 設定** 及專案啟動腳本的完整流程。

---

## 1. 安裝 Docker Desktop

### 1.1 Windows 10/11

#### 1.1.1 前置：啟用虛擬化與安裝 WSL 2

# 以系統管理員身分執行
wsl --install                 
wsl --set-default-version 2    # 設定預設為 WSL 2

> 若 `wsl --install` 不支援，可手動啟用功能
>
> ```powershell
> dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
> dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
> ```
>
> **重新開機**後，從 Microsoft Store 安裝 **Ubuntu 22.04 LTS**（或其他發行版），並確認：
>
> ```powershell
> wsl --status # Version 應顯示 2
> ```

#### 1.1.2 安裝 Docker Desktop

1. 下載安裝程式：[https://www.docker.com/products/docker-desktop](https://www.docker.com/products/docker-desktop)

2. 執行 **Docker Desktop Installer.exe**，並勾選 **Use WSL 2 based engine**。
3. 完成後**重新登入與重開機**，右下角可見小鯨魚圖示。
4. 驗證：

   docker run hello-world

### 1.2 macOS（Apple Silicon / Intel）

brew install --cask docker
open -a Docker      # 第一次執行會要求授權

> 無 Homebrew 時，可從官方 dmg 下載並拖曳至 Applications。

### 1.3 Linux（以 Ubuntu 22.04 為例）

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg lsb-release
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo usermod -aG docker $USER   # 將目前使用者加入 docker 群組
newgrp docker                    # 立即生效

docker run hello-world

> 其他發行版請參考官方文件：[https://docs.docker.com/engine/install/](https://docs.docker.com/engine/install/)

---

## 2. 環境需求

| 作業系統 | 測試版本 | 必備軟體 | 其他需求 |
| ----------- | ----------------- | ------------------------------------ | ------------------------ |
| **Windows** | 10 21H2 / 11 23H2 | Docker Desktop 4.30+ (WSL 2 backend) | 已安裝 WSL 2、啟用虛擬化 |
| **Linux** | Ubuntu 22.04 | Docker Engine 26+ | 使用者已加入 `docker` 群組 |
| **macOS** | 14 Sonoma | Docker Desktop 4.30+ | 支援 Apple Silicon / Intel |

---

## 3. 系統啟動流程圖

flowchart TD
    start(( ))
    subgraph 1["使用 Docker&nbsp;Compose<br/>管理 GPU/CPU 雙容器"]
    end
    script["一鍵啟動腳本自動偵測環境<br/>(run.bat / run.sh)"]
    decision{有 GPU?}
    gpu["啟動 GPU 容器"]
    cpu["啟動 CPU 容器"]
    endcircle(( ))
    
    start --> 1 --> script --> decision
    decision -- 是 --> gpu --> endcircle
    decision -- 否 --> cpu --> endcircle

---

## 4. 快速開始

### 4.1 Linux / macOS / WSL

cd /path/to/project-root        # ① 切換到專案根目錄
chmod +x run.sh                 # ② 初次使用把他改為可執行檔案
./run.sh                        # ③ 執行

### 4.2 Windows

:: 於 PowerShell 或 CMD 執行
cd C:\path\to\project-root
run.bat

---

## 5. 常用指令速查

| 指令 | 作用 | 備註 |
| ------------------------ | ---------------- | --------------- |
| `docker run hello-world` | 驗證 Docker 安裝 | 任一終端機皆可執行 |
| `cd <path>` | 切換工作目錄 | `<path>` 為專案根目錄 |
| `chmod +x run.sh` | 將 `run.sh` 變為可執行 | Linux/macOS/WSL |
| `./run.sh` / `run.bat` | 啟動專案 | Linux/macOS/WSL：使用 ./run.sh Windows：使用 run.bat

---

## 6. 常見問題

| 問題 | 解法 |
| ----------------------------------------- | -------------------------------------------------------------------------------- |
| `error: WSL 2 installation is incomplete` | 重開機或重新執行 `wsl --install`，確認 Windows 版本 ≥ 19044。 |
| `Docker Desktop failed to start` | 檢查 BIOS 虛擬化已開、Windows Features 內 **Hyper-V** & **Virtual Machine Platform** 已勾選。 |
| `./run.sh: Permission denied` | 確認已執行 `chmod +x run.sh`，或改用 `bash run.sh`。 |
| Windows 無法執行 `run.bat` | 右鍵→屬性→解除封鎖，或確認防毒軟體未隔離批次檔。 |
| macOS 想用 GPU？ | 目前 Apple Silicon / Intel Mac 皆不支援 CUDA，僅可使用 CPU 版。|

---

© 2025 Charlie ‧ License: MIT