# 終端機模組:docker(容器管理與應用)

給課程作者看的說明。啟用方式:terminal 單元的 `config` 加上 `'modules' => ['docker']`,初始世界用 `'world' => ['docker' => [...]]` 提供。
所有指令都是記憶體中的模擬(不會碰真實 Docker),輸出盡量貼近 Docker Engine 27 / Compose v2 / BuildKit(Ubuntu 24.04)。
模擬器內有一個固定起點(2026-11-06 09:00 UTC)的虛擬時鐘,每執行一次 docker 指令前進 2 秒,所以 `docker ps` 會看到 `Up 8 seconds`、`Exited (0) 12 seconds ago` 這類會隨操作變化的時間;`reset` 會整個重建。

> 與 `admin` 模組同時啟用時,兩邊都定義了 `curl`,**後面列的模組會蓋掉前面的**。需要用 `curl localhost:埠` 連容器時,請把 `docker` 放在 `modules` 最後面(`['admin', 'docker']`)。

## 支援的指令

### 容器
| 指令 | 支援的選項 / 行為 |
|---|---|
| `docker run` / `create` | `-d --name -p -P -v --mount -e --env-file --rm -it(見下) --network --restart -m -u -w -h --entrypoint -l --link --expose`;其他真實存在的旗標(`--cpus --privileged --cap-add --dns …`)接受但不影響結果。本機沒有映像會自動 pull;名稱衝突、port 已被占用、network/掛載不存在都有真實錯誤與 exit code(125 / 127) |
| `docker ps` | `-a -q -l -n N --no-trunc -s --format`、`--filter name= id= status= ancestor= label= network= volume= publish= exited=` |
| `docker stop / start / restart / kill / rm` | `rm -f -v`;`start -a`;不存在的容器、移除執行中容器等錯誤訊息與真實相同 |
| `docker logs` | `--tail N / -n`、`-t`、`--since 10s`;**`-f` 不支援**(回誠實訊息) |
| `docker exec` | `-it -e -u -w -d`;帶指令執行。`-it` 不帶指令(進入互動 shell)不支援,會建議改成帶指令執行 |
| `docker inspect` | 容器 / 映像 / volume / network 的 JSON 子集;`-f '{{.State.Status}}'`、`{{.NetworkSettings.IPAddress}}`、`{{json .Config.Env}}`;`{{range}}`、`{{if}}` 不支援(回誠實訊息) |
| `docker top`、`docker stats --no-stream`、`docker port`、`docker rename`、`docker pause / unpause`、`docker wait`(僅已結束的容器)、`docker update --restart/-m` | 簡化輸出 |
| `docker cp` | 主機 ↔ 容器(檔案或目錄,讀寫虛擬檔案系統);`docker commit [-m -a -c] 容器 [名稱:tag]` 會把容器內被改過的檔案存成新映像 |
| `docker container ls/run/rm/prune …`、`docker image ls/rm/pull/prune …` | 與短指令等效 |

`docker run -it 映像`(沒有指令、會進入互動 shell)與 `docker exec -it 容器 sh` 都不支援,會回:`練習環境不支援互動式的 -it …請改成帶指令的方式`。`docker run -it --rm alpine ls /` 這種帶指令的寫法可以。
`docker run` 不加 `-d`:會印出輸出;如果容器是長時間執行的服務,輸出後附一行說明「已在背景啟動,等同 -d」(模擬器無法持續附著)。`sleep N` 這類有限時間的指令會直接等它結束。
`docker run -i` 搭配管線(`echo "ls /" | docker exec -i web sh`)可執行 stdin 內的指令。

### 映像
| 指令 | 說明 |
|---|---|
| `docker pull [名稱[:tag]]` | 逐層 `Pull complete` 輸出;沒給 tag 先印 `Using default tag: latest`;已存在印 `Image is up to date`;找不到印 `pull access denied …` 或 `manifest for x:y not found` |
| `docker images / image ls` | `-a -q --no-trunc --digests --format`、`--filter dangling= reference=`、可帶 `repo[:tag]` |
| `docker rmi / image rm` | `-f`;多個 tag 只 `Untagged`;被容器使用時有真實的 conflict 錯誤 |
| `docker tag`、`docker history [-q --no-trunc]` | history 顯示每個指令的層(內建映像為合成的層) |
| `docker build` | 見下節 |
| `docker login / logout / push / search` | 見「registry」 |
| `docker image prune [-a] -f`、`docker container prune -f`、`docker volume prune [-a] -f`、`docker network prune -f`、`docker system prune [-a] [--volumes] -f`、`docker system df`、`docker info`、`docker version` | **prune 沒加 `-f` 會回說明並失敗**(模擬器無法互動輸入 y,與真實的互動提示對應) |

### docker build(讀取虛擬檔案系統的 Dockerfile)
- 指令:`docker build -t 名稱[:tag] [-f 檔案] [--no-cache] [--build-arg K=V] [--target 階段] [-q] 路徑`(`docker buildx build` 同義)。
- Dockerfile 支援:`FROM`(含 `AS`、多階段、`scratch`、`ARG` 變數)、`RUN`、`COPY`/`ADD`(`--from=階段`、萬用字元、`.`、目錄)、`WORKDIR`、`ENV`、`ARG`、`EXPOSE`、`USER`、`CMD`、`ENTRYPOINT`(exec 與 shell 形式)、`VOLUME`、`LABEL`、`HEALTHCHECK`/`SHELL`/`STOPSIGNAL`/`ONBUILD`(只解析)。
- 輸出是 BuildKit 風格:`[+] Building … FINISHED`、`=> [internal] load build definition from Dockerfile`、`=> [2/5] WORKDIR /app`、`=> CACHED [3/5] …`、`exporting to image`、`naming to docker.io/library/名稱:tag`。**為了讓 `solution` 驗證不把它當錯誤,成功時整段進度寫在 stdout;失敗時整段寫在 stderr、exit 1。**
- 會失敗的情況(都有 BuildKit 風格的錯誤、`>>>` 標出 Dockerfile 的出錯行):`COPY` 來源不存在(含被 `.dockerignore` 排除)、未知指令(`unknown instruction: RNU`)、找不到 Dockerfile、`FROM` 的映像不存在、`RUN` 指令失敗(`exit 3`、找不到指令=127)。
- `.dockerignore` 會被讀取(`*`、`**`、`?`、目錄名、`!` 例外);context 大小會反映被排除的結果。
- `RUN` 內可以:`echo > 檔`、`mkdir -p`、`touch`、`rm`、`cat`、`ls`、`pip install [-r requirements.txt]`(需 python 映像,`-r` 檔案要先 COPY 進來)、`npm install`(需 package.json)、`apt-get update && apt-get install -y 套件`(**debian/ubuntu 沒先 `apt-get update` 會失敗 `Unable to locate package`**)、`apk add`(alpine)。其他常見指令(`chmod`、`useradd`、`cp`…)視為成功的空操作;`curl` 等工具在映像裡沒有時回 127(`curl: not found`)。
- 相同內容再建一次會出現 `CACHED`,並得到同一個映像 id;改檔案內容會讓該步驟之後的快取失效。
- 建好的映像:沿用基底映像的行為(例如以 nginx 為基底只 COPY 網頁,`curl localhost:埠` 會回你 COPY 的頁面);改了 `CMD`/`ENTRYPOINT` 時,依指令推測行為——`python app.py`/`node app.js` 會讀映像裡的腳本:有 `print`/`console.log` 就印到 logs,有 `app.run`/`listen`/`http.server`… 就當成長時間執行的服務(埠取自程式碼或 `EXPOSE`),`return "…"` / `res.send('…')` 的字串當成 HTTP 回應。要精確控制請用 `world.behaviors`。

### volume
`create [名稱]`、`ls [-q --filter dangling=/name=]`、`rm`(使用中:`volume is in use - [容器id]`)、`inspect`、`prune [-a] -f`。
`docker run -v 名稱:/路徑` 不存在會自動建立;映像宣告的 `VOLUME`(例如 mariadb 的 `/var/lib/mysql`、redis 的 `/data`)沒掛載時會建立**匿名 volume**(64 位十六進位名稱)——可用來教 `volume prune`。
資料庫容器掛了有資料的 volume 之後,即使不給密碼也能啟動(資料已初始化),可展示「容器刪了資料還在」。

### network
`create [--driver --subnet --internal --label]`、`ls`、`rm`(使用中:`has active endpoints`;預設網路:`pre-defined network and cannot be removed`)、`inspect`(含 `Containers`、`IPAM.Config`)、`connect [--alias]`、`disconnect`、`prune -f`。
- 預設 `bridge` 網路(172.17.0.0/16)的容器**不能**用名稱互相解析;自訂 bridge 網路內可以用「容器名稱」「網路別名」「compose 服務名稱」解析,`curl http://api`、`ping api`、`wget -qO- http://api` 都會成功。找不到:`curl: (6) Could not resolve host: x`、`ping: bad address 'x'`(alpine / busybox)或 `Name or service not known`(debian)。
- `--network host` 的容器直接占用主機埠;`--link 名稱:別名` 在預設 bridge 上提供別名。

### 容器內可執行的指令(docker exec / docker run 指令 / Dockerfile RUN)
`sh -c`(支援 `;`、`&&`、`||`、`|`、`>`、`>>`、`2>&1`、`$VAR`、`cd`、`export`、`exit`)、`ls [-l -a -1 -F]`、`cat`、`echo`、`env`/`printenv`、`hostname [-i]`、`whoami`、`id`、`pwd`、`date`、`uname`、`ps`(alpine 為 busybox 格式;debian 支援 `aux`、`-ef`)、`head`、`tail`、`wc`、`grep`、`sort`、`uniq`、`touch`、`mkdir [-p]`、`rm [-r -f]`、`sleep`、`curl`、`wget`、`ping [-c]`、`nslookup`、`redis-cli`(ping set get del exists incr keys dbsize flushall info)、`nginx -v/-t/-s reload`、`python/node --version|-c|腳本`、`pip install`、`npm install`、`apt-get update/install`、`apk add`。
- **工具集依映像而定(貼近真實)**:alpine / busybox 有 `ping`、`wget`、`nslookup`,**沒有 `bash` 與 `curl`**(`docker exec web bash` 會得到 `executable file not found in $PATH`);debian / ubuntu 有 `bash`;nginx、python、node 映像有 `curl`;ubuntu、debian、mariadb 等沒有 `curl`、`ping`。學員可以在容器內 `apt-get update && apt-get install -y curl iputils-ping`(或 alpine 的 `apk add curl`)補裝;課程也可用 `world.exec_tools: ['curl','ping']` 讓所有容器都有,或在映像定義加 `tools`。
- 寫入(`>`、`touch`、`mkdir`)會真的改變容器檔案系統:寫進 bind mount 會改到虛擬主機檔案;寫進 volume 會留在 volume;其餘寫在容器層(`docker commit` / `docker cp` 看得到)。`ping` 沒給 `-c` 時預設送 4 筆。
- 其他指令:`cp mv chmod find sed awk tar vim top mysql psql …` 回「練習環境尚未支援在容器內執行 X」;完全不存在的名稱回 OCI runtime exec failed(exit 126)。

### docker compose(內含小型 YAML 解析器)
- 讀 `compose.yaml` / `compose.yml` / `docker-compose.yaml` / `docker-compose.yml`(從目前目錄往上找),或 `-f` 指定(可多個,深層合併)、`-p` 專案名稱、`--env-file`、`--project-directory`。專案名稱預設為檔案所在目錄名(或頂層 `name:`)。
- 子指令:`up [-d --build --force-recreate --no-recreate]`(沒加 `-d` 會印出日誌並說明已改為背景)、`down [-v]`、`ps [-a -q --services]`、`logs [--tail N -t] [服務…]`(`-f` 不支援)、`stop / start / restart / kill / pause / unpause [服務…]`、`rm -f`、`exec [-T -e -u -w] 服務 指令`、`pull`、`build [--no-cache]`、`config [-q --services --volumes --networks -o 檔]`(輸出展開後的簡化 YAML)、`ls`、`version`。`run`、`cp`、`watch`、`scale`… 回「尚未支援」。
- 服務欄位:`image build(字串或 context/dockerfile/args/target) ports environment(map 與 list) env_file volumes(具名 / bind / 匿名 / 長語法) networks depends_on(list 或含 condition 的 map) restart command entrypoint healthcheck(只解析) container_name working_dir user hostname labels profiles network_mode expose`,其他 compose 規格內的鍵(`deploy`、`logging` …)接受但忽略。頂層 `volumes`、`networks`(含 `external`、`name`、`driver`)。
- `${VAR}`、`${VAR:-預設}`、`${VAR:?錯誤}` 會用同目錄 `.env` 檔展開,未設定的變數印 `WARN[0000] The "X" variable is not set. Defaulting to a blank string.`;`version:` 印 obsolete 警告(寫在 stderr)。
- 有意義的錯誤:YAML 語法(`yaml: line 5: mapping values are not allowed in this context`、`could not find expected ':'`、縮排錯誤)、`service "web" refers to undefined volume data: invalid compose project`、`… undefined network backend`、`has neither an image nor a build context specified`、`depends on undefined service`、`dependency cycle detected: a -> b -> a`、`validating …/compose.yaml: services.web additional properties 'imag' not allowed`、`no configuration file provided: not found`。
- 命名規則同 Compose v2:容器 `專案-服務-1`、網路 `專案_default`、volume `專案_名稱`、映像(只有 build)`專案-服務`;容器會帶 `com.docker.compose.*` 標籤,服務間可用服務名稱互相連線。設定有變動再 `up -d` 會 `Recreated`。
- `docker-compose`(舊名稱):回 `Command 'docker-compose' not found …` 並提示改用 `docker compose`。

### curl(主機端)
模組提供 `curl`:`curl [-s -S -i -I -L -f -v -k -o 檔 -O -X 方法 -H -d -w '%{http_code}'] URL`。主機端只能連 `localhost` / `127.0.0.1` / `0.0.0.0` 加上**已發佈的主機埠**(`-p 8080:80` → `localhost:8080`)、容器 IP,以及 `world.http` 設定的位址。
- 容器沒發佈該埠:`curl: (7) Failed to connect to localhost port 8080 after 0 ms: Couldn't connect to server`。
- 埠有對應但容器內程式沒在聽那個埠(例如 `-p 8080:8080` 卻是 nginx):`curl: (52) Empty reply from server`。
- 主機端無法用容器名稱解析:`curl: (6) Could not resolve host: web`。
- nginx / httpd 映像會依容器內 `/usr/share/nginx/html`(httpd:`/usr/local/apache2/htdocs`)的實際內容回應:bind mount 的主機檔案、`docker cp` / `COPY` 進去的檔案都會生效,沒有 `index.html` 回 403,沒有該檔回 404;每次請求會寫一行 access log 到 `docker logs`。
- 學員用 `curl -s -o /dev/null -w "%{http_code}"` 取得狀態碼也可以。

### 權限
`world.docker_group`(預設 `true`)。設為 `false` 且不是 `sudo` 時,所有 docker 指令回:
`permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Get "http://%2Fvar%2Frun%2Fdocker.sock/v1.47/containers/json": dial unix /var/run/docker.sock: connect: permission denied`(exit 1;`docker run` 為 `docker: …` 並 exit 126)。`docker version` 會先印 Client 區塊再印錯誤。
加上 `sudo` 即可執行。若同時啟用 `admin` 模組,`/etc/group` 內出現 `docker:x:…:student` 也視為已加入群組(`sudo usermod -aG docker student` 之後生效;模擬器不需要重新登入)。

## 不支援(回誠實訊息或 command not found)
`docker run -it` 互動 shell、`logs -f`、`stats`(沒有 `--no-stream`)、`compose logs -f`、`compose run`、`attach`、`events`、`save/load/export/import`、swarm / stack / service、`context`(除 `ls`)、`buildx` 其他子指令、`wait` 執行中的容器、`$(…)` 命令替換與 `xargs`(核心不支援,所以 `docker rm $(docker ps -aq)` 無法使用,請教學員直接列容器名稱,或用 `docker container prune -f`;例外:`-v $(pwd)/x:/y` 的 `$(pwd)` 模組會自己展開)、容器內的 `mysql` / `psql` 客戶端、`docker run --gpus` 等硬體選項(接受但無效果)。

## world 設定格式

```php
'world' => ['docker' => [
    'docker_group' => true,                 // false = 學員不在 docker 群組,需要 sudo
    'internet' => true,                     // 容器內 ping 外部網域是否成功(預設 true);curl 外部網站要在 http 設定,否則 Could not resolve host
    'exec_tools' => ['curl', 'ping'],       // 讓所有容器都有這些工具(預設依映像)
    'ports_in_use' => [80, ['port' => 5432, 'service' => 'postgresql']],  // 主機上已被占用的埠(docker run -p 80:80 會失敗)
    'http' => [                             // 非容器的 HTTP 位址(curl localhost:9000)
        'localhost:9000' => 'external service',
        '3000' => ['status' => 200, 'body' => '{"ok":true}'],
    ],
    'registry' => [                         // docker login / push
        'users' => ['alice' => 'secret'],   // 省略 = 任何帳密都登入成功;給了就必須帳密相符
        'namespace' => 'alice',             // push 只允許 alice/xxx(預設 = 登入的帳號)
    ],
    'images' => [                           // 可從 registry 拉的額外映像(內建官方映像見下)
        'myorg/base:1.0',                   // 字串 = 最簡單的映像
        ['name' => 'shop/api', 'tags' => ['1.0', 'latest'], 'size' => '120MB', 'description' => '商店 API',
         'cmd' => ['node', 'server.js'], 'env' => ['PORT' => '3000'], 'exposed' => [3000], 'os' => 'alpine',
         'tools' => ['curl'], 'files' => ['/app/server.js' => "console.log('hi')\n"],
         'behavior' => [...]],              // 見下
    ],
    'behaviors' => [                        // 替「用 Dockerfile 建出來」或內建的映像追加行為,key = 映像名稱或 名稱:tag
        'myapp' => ['listens' => 5000, 'logs' => ['starting']],
    ],
    'local' => [                            // 一開始就存在於本機的東西
        'images' => ['nginx:1.25', ['name' => 'myorg/api:1.0', 'size' => '90MB']],
        'volumes' => ['olddata', ['name' => 'v2', 'files' => ['/note.txt' => 'hi']]],
        'networks' => ['legacy', ['name' => 'backend', 'subnet' => '172.30.0.0/16']],
        'containers' => [
            ['name' => 'web', 'image' => 'nginx:1.25', 'state' => 'running',   // running | exited | created
             'ports' => ['8080:80'], 'env' => ['A' => '1'], 'volumes' => ['olddata:/data'], 'network' => 'legacy',
             'restart' => 'always', 'logs' => ['自訂日誌行'], 'exit_code' => 0, 'age_seconds' => 7200],
        ],
    ],
]],
```

### 內建的官方映像(`docker pull` / `docker run` 自動拉取)
`hello-world`、`nginx`(`latest 1.27 1.26 1.25 stable alpine 1.27-alpine …`)、`httpd`、`alpine`(`3.18~3.20`)、`ubuntu`(`20.04 22.04 24.04`)、`debian`、`busybox`、`python`(`3.11~3.13`、`-slim`、`alpine`)、`node`(`18 20 22`、`-slim`、`-alpine`)、`mariadb`(`10.6 10.11 11 11.4`)、`mysql`(`8.0 8.4 9`)、`postgres`(`15 16 17`、`-alpine`)、`redis`(`6.2 7 7.4`、`-alpine`)、`memcached`。大小、層數、說明、建立時間都是固定值。其他名稱 pull 會得到 `pull access denied`。
內建的行為(貼近真實):
- `nginx`:監聽 80,日誌是真實的啟動日誌,提供網頁;`mariadb` / `mysql`:沒有 `MARIADB_ROOT_PASSWORD`(或 `MYSQL_ROOT_PASSWORD` 等三選一)就立即結束 `Exited (1)` 並印真實的錯誤日誌;`postgres`:沒有 `POSTGRES_PASSWORD` 結束;`redis`:監聽 6379,容器內可 `redis-cli ping`。
- `alpine` / `ubuntu` / `busybox` / `python` / `node`:預設 CMD 是 shell / REPL,**沒有 `-it` 時立刻結束 `Exited (0)`**(與真實相同);`docker run -d alpine sleep 3600` 才會持續執行。`hello-world` 印標準歡迎訊息後結束。

### 映像 `behavior`(替自訂映像編排排錯情境)
可寫在 `images[].behavior`、`local.images[]`,或 `world.behaviors[映像名]`。字串形式 `'behavior' => 'exits-immediately'` 等於 `['exits-immediately' => true]`。鍵名的 `-` 與 `_` 視為相同。

| 欄位 | 說明 |
|---|---|
| `exits-immediately`(或 `exits`) | 啟動就結束:`docker run -d` 之後 `ps` 看不到、`ps -a` 顯示 `Exited (退出碼)`、`logs` 看得到 `logs` 的內容。`exits` 給數字就是退出碼 |
| `exit_code` | 退出碼(預設 1) |
| `listens` | 容器內監聽的埠(數字或陣列);才能用 `curl localhost:對外埠` 取得回應、容器間 `curl http://容器名:埠` |
| `logs` | 啟動日誌行(陣列);可用 `${環境變數}`,例如 `'server on ${PORT}'` |
| `http` | 回應內容:字串(所有路徑)或 `['/' => '首頁', '/api' => ['status' => 200, 'body' => '{"ok":true}', 'type' => 'application/json']]` |
| `connects` | `[['host' => 'db', 'port' => 3306]]`:啟動時若連不到(名稱解析不到 / 沒在聽)就失敗 `Error: getaddrinfo ENOTFOUND db`,exit 1。`host` 可用 `${DB_HOST}`。`connect_error` 可自訂錯誤行(可含 `{host}`、`{port}`) |
| `requires_env` / `requires_any_env` | 缺少這些環境變數就失敗 |
| `raw_tcp` | 監聽的不是 HTTP(`curl` 得到 `Empty reply from server`) |
| `access_log` | 每個請求寫一行 access log |

沒有 `--restart` 的失敗容器就是結束;加 `--restart always|unless-stopped|on-failure[:N]` 的失敗容器會變成 `Restarting (1) 3 seconds ago`(重啟次數隨虛擬時間增加,`docker inspect` 的 `RestartCount` 與 `logs` 重複的啟動日誌反映這個迴圈)——可用來教「容器一直重啟」的排錯。

## check 類型(寫在任務的 `check` / `checks`)
| type | 欄位 | 說明 |
|---|---|---|
| `container` | `name`(省略 = 任一容器)、`state`=`running`\|`exited`\|`created`\|`restarting`\|`paused`\|`absent`\|`any`(預設 any)、`image`(`nginx` 比 repo,`nginx:1.25` 比完整)、`port`(`'8080:80'`、`'127.0.0.1:8080:80'`、`'80'`,可給陣列 `ports`)、`env`(map、`['K=V']` 或 `'K=V'`,含有即成立,包含映像內建的環境變數)、`volume`(`'資料名:/路徑'`、`'~/site:/usr/share/nginx/html'`、只給路徑或名稱;可陣列)、`network`、`restart`(`always` 等)、`user`、`exit_code`、`cmd`(指令包含文字)、`label`(`k=v`)、`logs_contain` | 容器狀態與設定。`state: absent` 在**一開始容器本來就不存在時會立刻成立**——請搭配 `ran` 一起放在 `checks`(例如 `^docker rm`)或讓世界一開始就有該容器 |
| `image` | `name`(`nginx:1.25`;不寫 tag = 任一 tag,可寫映像 id 前綴)、`state`=`absent`(或 `exists => false`) | 映像存在 / 不存在 |
| `volume` | `name`、`state`=`absent`、`used_by`(容器名稱)、`contains`(volume 內有檔名或內容包含此文字) | volume 存在 |
| `network` | `name`、`state`=`absent`、`contains`(容器名稱或陣列)、`driver`、`subnet` | 自訂網路存在、含有容器 |
| `built` | `name`(`myapp:1.0`,學員用 `docker build -t` 建出的映像)、`dockerfile`(檔名)、`from`(基底映像)、`has_file`(映像內含檔案)、`cmd`(CMD/ENTRYPOINT 含文字)、`expose`(埠或陣列)、`env`、`workdir`、`user` | 以 Dockerfile 建出的映像(預先放在 `local.images` 的不算) |
| `pushed` | `name` | 成功 `docker push` 過該映像 |
| `logged_in` | `user`(可省略) | 成功 `docker login` |
| `http` | `url`(`localhost:8080`)、`contains`、`status`(`'down'` = 連不上) | 目前 curl 該位址會得到的內容(不會寫 access log) |
| `compose` | `project`、`service`、`state`(預設 running)、`count` | compose 專案的服務容器狀態 |

檔案類的檢查(`contains` / `exists` / `equals`…)沿用核心,可用來驗證學員寫的 Dockerfile 與 compose.yaml。`ran`(指令樣式)與 `out`(輸出樣式)也很適合純檢視型的任務。
注意:任務一旦完成就不會取消;任務在**一開始不能已經成立**(`validate-terminal` 會檢查)。

## 完整的 terminal 單元範例

```php
['title' => '練習:從映像到容器,再把網頁打包成自己的映像', 'type' => 'terminal', 'xp' => 40,
 'content' => <<<'TXT'
你剛接手一台新的開發機。先把官方 nginx 1.25 映像拉下來,用它在背景啟動一個名叫 web 的容器(主機 8080 對應容器 80),用 curl 確認首頁。之後要換成自己的版本:家目錄的 myapp 資料夾裡有 Dockerfile 與 index.html,請建成 myapp:1.0,再用它跑一個 site 容器(主機 9090),確認 curl 看到的是你自己的頁面。順便練習清理:web 容器用完要先停止再刪除;另外建一個自訂網路 appnet,在裡面跑一個名為 cache 的 redis。
TXT,
 'config' => [
    'modules' => ['docker'],
    'cwd' => '~',
    'fs' => ['home' => ['student' => [
        'myapp' => [
            'Dockerfile' => "FROM nginx:1.25\nCOPY index.html /usr/share/nginx/html/index.html\nEXPOSE 80\n",
            'index.html' => "<h1>我的第一個映像</h1>\n",
        ],
    ]]],
    'world' => ['docker' => ['docker_group' => true]],
    'tasks' => [
        ['title' => '拉取 nginx:1.25 映像', 'hint' => 'docker pull nginx:1.25',
         'check' => ['type' => 'image', 'name' => 'nginx:1.25']],
        ['title' => '以背景模式啟動 web 容器,主機 8080 → 容器 80', 'hint' => 'docker run -d --name web -p 8080:80 nginx:1.25',
         'check' => ['type' => 'container', 'name' => 'web', 'state' => 'running', 'image' => 'nginx:1.25', 'port' => '8080:80']],
        ['title' => '用 curl 確認首頁', 'hint' => 'curl localhost:8080',
         'checks' => [['type' => 'ran', 'pattern' => '^curl .*8080'], ['type' => 'out', 'pattern' => 'Welcome to nginx']]],
        ['title' => '停止並刪除 web 容器', 'hint' => 'docker stop web,再 docker rm web',
         'checks' => [['type' => 'ran', 'pattern' => '^docker rm\b'], ['type' => 'container', 'name' => 'web', 'state' => 'absent']]],
        ['title' => '建立 appnet 網路並在裡面跑 cache(redis)', 'hint' => 'docker network create appnet;docker run -d --name cache --network appnet redis',
         'checks' => [['type' => 'network', 'name' => 'appnet', 'contains' => ['cache']], ['type' => 'container', 'name' => 'cache', 'state' => 'running', 'network' => 'appnet']]],
        ['title' => '用 Dockerfile 建出 myapp:1.0', 'hint' => 'cd myapp 之後 docker build -t myapp:1.0 .',
         'check' => ['type' => 'built', 'name' => 'myapp:1.0', 'has_file' => '/usr/share/nginx/html/index.html']],
        ['title' => '用 myapp:1.0 啟動 site 容器(主機 9090),curl 看到自己的頁面', 'hint' => 'docker run -d --name site -p 9090:80 myapp:1.0',
         'checks' => [['type' => 'container', 'name' => 'site', 'state' => 'running', 'port' => '9090:80'], ['type' => 'http', 'url' => 'localhost:9090', 'contains' => '我的第一個映像']]],
    ],
    'solution' => [
        'docker pull nginx:1.25', 'docker run -d --name web -p 8080:80 nginx:1.25', 'curl localhost:8080', 'docker stop web', 'docker rm web',
        'docker network create appnet', 'docker run -d --name cache --network appnet redis',
        'cd myapp', 'docker build -t myapp:1.0 .', 'docker run -d --name site -p 9090:80 myapp:1.0', 'curl localhost:9090',
    ],
 ],
],
```

### 寫排錯型任務的小訣竅
- 「容器一直重啟」:`images` 放一個 `behavior => ['exits-immediately' => true, 'logs' => ['Error: DB_URL is not set']]` 的映像,`local.containers` 預先放一個用它、`restart => 'always'` 的容器,任務是 `docker logs` 找原因後 `docker rm -f` 重新用 `-e DB_URL=…` 啟動(再把映像 behavior 改成 `requires_env => ['DB_URL']` 就能讓「補上環境變數」真正修好它)。
- 「port 被占用」:`ports_in_use => [8080]`,或讓 `local.containers` 已有占用 8080 的容器。
- 「連不到資料庫」:映像 `behavior => ['connects' => [['host' => 'db', 'port' => 3306]]]`;預設 bridge 解析不到 → 學員要建自訂網路,把 db 與 app 放進同一個網路。
- 「資料持久化」:資料庫容器掛具名 volume → `docker rm -f` → 再起一個容器掛同一個 volume,`docker exec` 仍看得到檔案(`world` 不用額外設定,mariadb / mysql / postgres 啟動時會把資料檔放進掛在資料目錄的 volume)。
- 「Dockerfile 排錯」:給有 `COPY` 打錯檔名、`apt-get install` 沒先 `update`、`RNU` 打錯指令的 Dockerfile,任務是修好(用 `echo … > Dockerfile` 重寫)後 `built` 成功。
