From 989fe0164e206ce31d8e67bbf241e08b85ca835b Mon Sep 17 00:00:00 2001
From: Timmy <loyangchun@gmail.com>
Date: Sat, 20 Jun 2026 23:19:14 +0800
Subject: [PATCH] Add Apple container setup notes

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 container-setup.md | 124 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 124 insertions(+)
 create mode 100644 container-setup.md

diff --git a/container-setup.md b/container-setup.md
new file mode 100644
index 0000000..5f8e970
--- /dev/null
+++ b/container-setup.md
@@ -0,0 +1,124 @@
+# 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` 可保留使用者資料。）