# Apple `container` 安裝與使用筆記

> 工具：[apple/container](https://github.com/apple/container) — 在 macOS 上以輕量虛擬機執行 Linux 容器
> 安裝日期：2026-06-20
> 安裝版本：**v1.0.0**

---

## 環境

| 項目 | 值 |
|------|-----|
| 機器 | Apple Silicon（arm64） |
| macOS | 15.5（Sequoia） |
| 安裝方式 | Homebrew formula |

> ⚠️ **版本注意**：官方文件標示 `container` 只支援 **macOS 26+**，因為它依賴 macOS 26 對虛擬化與網路的新功能。
> Homebrew formula 的需求較寬鬆（arm64 + macOS >= 15），因此可在 macOS 15.5 上安裝執行。
> 但在 macOS 15 上**網路功能受限**（例如多容器各自取得獨立 IP 的功能無法運作），且官方不受理 macOS 15 的問題回報。
> 一般本機測試容器（build / run）可正常使用。

---

## 安裝步驟（實際採用：Homebrew）

```bash
brew install container
```

- 安裝路徑：`/opt/homebrew/bin/container`
- 不需要 sudo（裝在 `/opt/homebrew`）
- 驗證版本：
  ```bash
  container --version
  # container CLI version 1.0.0
  ```

### 替代方案：官方簽章安裝器

若改用官方 `.pkg`（會裝到 `/usr/local`，需管理員密碼）：

1. 從 [Releases](https://github.com/apple/container/releases) 下載 `container-1.0.0-installer-signed.pkg`
2. 雙擊安裝，或：
   ```bash
   sudo installer -pkg container-1.0.0-installer-signed.pkg -target /
   ```

---

## 啟動服務

```bash
# 方式 A：本 session 啟動（手動）
container system start

# 方式 B：背景常駐 + 開機自動啟動（建議長期使用）
brew services start container
```

### 首次啟動需設定 kernel

第一次啟動會要求安裝預設 Linux kernel。若互動提示無法回應，改用明確指令：

```bash
container system kernel set --recommended
```

- 會從 kata-containers releases 下載推薦 kernel（本次為 Kata 3.28.0 arm64）
- 下載約數十 MB，需稍候

---

## 驗證安裝

```bash
container system status
# status: running

container run --rm docker.io/library/alpine echo "hello from container"
# → hello from container
```

> 首次執行某個 image 時會額外下載 init image（約 64MB），之後會被快取。

---

## 常用指令

```bash
# 跑一個容器（用完即刪）
container run --rm docker.io/library/alpine echo hello

# 互動式 shell
container run -it --rm docker.io/library/alpine sh

# 列出執行中的容器
container ls

# 列出本機映像檔
container images ls

# 停止系統服務
container system stop
```

---

## 疑難排解

| 症狀 | 原因 / 解法 |
|------|------------|
| `default kernel not configured for architecture arm64` | kernel 未設定 → 執行 `container system kernel set --recommended` |
| `failed to read user input` | 互動提示無法回應 → 改用對應的非互動指令（如上面的 kernel set） |
| 網路相關異常 | macOS 15 的已知限制，非設定錯誤；需 macOS 26 才完整支援 |

---

## 移除

```bash
brew uninstall container
```

（若以官方 .pkg 安裝，則使用 repo 內的 `uninstall-container.sh`，加 `-k` 可保留使用者資料。）