{
 "byKey": {
  "cover": [
   { "say": "大家好,歡迎回到容器管理與應用。到目前為止,我們都是一個一個容器手動啟動。這一章要學 Docker Compose,把整組服務寫在一個檔案裡,一個指令就全部帶起來,還會談到環境變數、機密、健康檢查,以及一個三層應用的完整設計。", "item": 0 }
  ],
  "Compose 基礎:compose.yaml 與常用指令#1": [
   { "say": "先說為什麼需要 Compose。", "item": 0 },
   { "say": "一個真實的應用,往往不只一個容器,會有網站、資料庫、快取,還有反向代理。", "item": 1 },
   { "say": "如果全部用 docker run 手動啟動,指令又長,又容易漏掉選項,像是網路、volume、環境變數,還有啟動的順序,也很難交給同事照著重現。", "item": 1 },
   { "say": "Docker Compose 讓你把整個應用的所有服務,寫在一個 YAML 檔裡,用一個指令就能啟動、停止和重建。它就是容器版的基礎設施即程式碼。", "item": 1 }
  ],
  "Compose 基礎:compose.yaml 與常用指令#2": [
   { "say": "開始之前,有幾個現行寫法要提醒。網路上很多舊文章的寫法已經過時了。", "item": 0 },
   { "say": "第一,指令是 docker 空一格 compose,它是 Docker C L I 的外掛。不是舊的、中間用減號連起來的那個獨立程式,那個第一版已經停止維護了。", "item": 1 },
   { "say": "第二,檔名建議用 compose 點 yaml。其他幾種舊檔名也還支援。", "item": 2 },
   { "say": "第三,格式遵循的是 Compose Specification。舊檔案開頭常見的 version 欄位已經過時,現在的版本會忽略它,還可能顯示警告,所以新的檔案請不要再寫。", "item": 3 }
  ],
  "Compose 基礎:compose.yaml 與常用指令#3": [
   { "say": "來看一個最小的範例。檔案裡定義了一個叫 web 的服務,用的是 engine X 的映像檔,重啟策略設成 unless stopped。", "item": 0 },
   { "say": "ports 這一項,把主機本機位址的八零八零號埠,對應到容器的八十號埠,和減號 P 的寫法一樣。", "item": 1 },
   { "say": "volumes 這一項,把目前目錄底下的 site 資料夾,用唯讀的方式掛到放網頁的目錄,這就是上一章學的 bind mount。", "item": 2 },
   { "say": "這些設定都寫在最上層的 services 底下。一個 service,對應的就是一種容器。", "item": 3 },
   { "say": "寫好之後,用 docker compose up 加減號 D,在背景啟動。", "item": 4 },
   { "say": "你會看到它建立了一個網路,並且啟動了容器。Compose 會自動建立專屬的網路、需要的 volume,拉取或建置映像檔,再啟動容器。專案名稱預設取自目錄的名稱,也可以自己指定。", "item": 5 }
  ],
  "Compose 基礎:compose.yaml 與常用指令#4": [
   { "say": "接著認識常用的 service 欄位。build 是從某個目錄的 Dockerfile 來建置,image 是映像檔名稱,command 可以覆蓋 C M D,environment 則是直接寫環境變數。", "item": 0 },
   { "say": "另外 container name 可以固定容器的名稱,但通常不建議,因為會妨礙擴充副本。", "item": 0 },
   { "say": "E N V file 這個欄位,是從檔案把環境變數讀進來。", "item": 1 },
   { "say": "ports 是埠的對應,這裡同樣只綁在本機位址。", "item": 2 },
   { "say": "volumes 是掛載,這裡把一個叫 app data 的具名 volume,掛到容器的 data 目錄。", "item": 3 },
   { "say": "networks 是這個服務要加入哪些網路,例子裡是 backend。", "item": 4 },
   { "say": "depends on 則是說,這個服務要等 D B 先啟動。除此之外,還可以設定重啟策略、用哪個使用者執行,以及把根檔案系統設成唯讀。", "item": 5 }
  ],
  "Compose 基礎:compose.yaml 與常用指令#5": [
   { "say": "關於這些欄位,有幾個重點要記得。", "item": 0 },
   { "say": "第一,具名的 volume 和網路,要先在檔案最上層的 volumes 和 networks 宣告,服務裡面再去引用。", "item": 1 },
   { "say": "第二,同一個專案的服務,預設都在同一個網路,直接用服務名稱就能互連。例如把資料庫主機寫成 D B 就可以了,和第五章的觀念完全相同。", "item": 2 },
   { "say": "第三,YAML 是用空白來縮排的,最常見的是兩格,不能用 Tab。縮排錯誤,是新手最常見的失敗原因。", "item": 3 }
  ],
  "Compose 基礎:compose.yaml 與常用指令#6": [
   { "say": "還有一個小細節。", "item": 0 },
   { "say": "埠的對應,建議用引號包起來。因為 YAML 有可能把數字冒號數字這種寫法,當成六十進位的數字來解析,加了引號就不會有這個問題。", "item": 1 }
  ],
  "Compose 基礎:compose.yaml 與常用指令#7": [
   { "say": "最後看一下整個檔案的骨架,最上層有三個區塊。", "item": 0 },
   { "say": "services,底下定義每一個服務。", "item": 1 },
   { "say": "volumes,宣告具名的 volume。", "item": 2 },
   { "say": "networks,宣告自訂的網路。記住這個結構,以後看任何 compose 檔都不會迷路。", "item": 3 }
  ],
  "環境變數、健康檢查、啟動順序與 secrets#1": [
   { "say": "第二個單元,先看變數代換。Compose 會自動讀取專案目錄底下的點 E N V 檔,讓你在 compose 檔裡,用錢字號加大括號的方式引用變數。", "item": 0 },
   { "say": "像這個例子,主機的埠號不寫死,而是引用一個叫 app port 的變數,沒有設定的話就用預設的八千。", "item": 1 },
   { "say": "語法有三種。大括號裡只寫變數名稱,就是單純取值,沒有設定的話會是空字串,並且顯示警告。", "item": 2 },
   { "say": "變數名稱後面加上冒號和減號,再接一個值,意思是沒設定或是空的時候,就用這個預設值。", "item": 3 },
   { "say": "變數名稱後面加上冒號和問號,再接一段訊息,意思是沒設定就直接中止,並且顯示這段錯誤訊息。很適合用在一定要填的機密,例如資料庫密碼。", "item": 4 },
   { "say": "想看代換之後的結果,可以用 docker compose config。不過要小心,輸出會包含展開之後的密碼,不要貼到公開的地方。", "item": 4 }
  ],
  "環境變數、健康檢查、啟動順序與 secrets#2": [
   { "say": "對照實際的檔案來看。", "item": 0 },
   { "say": "先是點 E N V 檔。請記得把它加進點 gitignore,不要提交到版本控制。", "item": 1 },
   { "say": "裡面第一行是資料庫的 root 密碼,請自己產生一組隨機密碼。", "item": 2 },
   { "say": "第二行是應用程式的埠號,設成八千。", "item": 3 },
   { "say": "再來是 compose 檔。", "item": 4 },
   { "say": "在 services 底下,資料庫的密碼和應用程式的埠,就是用剛剛的語法去引用這兩個變數。", "item": 5 },
   { "say": "這裡要分清楚兩件事。點 E N V 檔是給 Compose 在解析檔案的時候做代換用的。要把變數真正傳進容器,還是要寫在 environment 或 E N V file 裡。", "item": 5 }
  ],
  "環境變數、健康檢查、啟動順序與 secrets#3": [
   { "say": "那 environment 和 E N V file 有什麼不同呢?", "item": 0 },
   { "say": "E N V file 是指向一個檔案,像這裡的點 E N V 點 app,把裡面的變數整批讀進容器,適合變數很多的情況。", "item": 1 },
   { "say": "environment 是直接把變數寫在 compose 檔裡。可以用名稱冒號值的對應寫法,也可以用清單的寫法。", "item": 2 },
   { "say": "不管用哪一種,和 docker run 的減號 E 一樣,環境變數都會被 docker inspect 看到。所以真正的機密,建議用接下來要介紹的 secrets。", "item": 3 }
  ],
  "環境變數、健康檢查、啟動順序與 secrets#4": [
   { "say": "secrets 是比環境變數更好的機密傳遞方式。它會把機密用檔案的形式,掛到容器裡 run secrets 這個目錄底下。不寫進映像檔,也不會出現在 docker inspect 的環境變數裡。", "item": 0 },
   { "say": "例子裡的機密叫 D B root password,服務要用哪些機密,就在自己的 secrets 欄位列出來。", "item": 1 },
   { "say": "在 services 這邊,資料庫的密碼變數名稱後面多了底線 FILE,值是機密檔案的路徑。官方的資料庫映像檔都支援這種寫法,會從檔案讀出密碼。", "item": 2 },
   { "say": "檔案最上層還要有一個 secrets 區塊,說明這個機密的內容,來自主機上的哪一個檔案。", "item": 3 },
   { "say": "這個機密檔本身,權限要設得很嚴格,只有擁有者能讀寫,並且加進點 gitignore。你自己寫的應用程式,也應該設計成可以從檔案讀取機密。", "item": 3 }
  ],
  "環境變數、健康檢查、啟動順序與 secrets#5": [
   { "say": "接下來是啟動順序,這裡有一個很多人會踩到的坑。depends on 只管啟動,不管服務是不是已經就緒。", "item": 0 },
   { "say": "像這樣寫 app 依賴 D B,只能保證 D B 的容器先被啟動,不代表資料庫已經可以接受連線。資料庫初始化可能要幾秒到幾十秒,app 太早去連就會失敗。", "item": 1 },
   { "say": "解法是替 D B 設定 healthcheck,再讓 app 等到它的狀態是健康,才啟動。也就是在 depends on 底下,把條件寫成 service healthy。", "item": 2 },
   { "say": "同時,應用程式本身也應該有連線重試的機制,因為資料庫在運作的過程中,也可能短暫重啟。", "item": 3 },
   { "say": "補充一下,例子用的是 Maria D B 官方映像檔內附的健康檢查腳本。其他映像檔要用各自適合的檢查方式,實作之前請對照它在 Docker Hub 上的說明。", "item": 3 }
  ],
  "環境變數、健康檢查、啟動順序與 secrets#6": [
   { "say": "看一下寫出來的樣子。", "item": 0 },
   { "say": "最單純的寫法,就是 app 底下的 depends on 只列出 D B,這只保證啟動的先後。", "item": 1 },
   { "say": "完整的寫法在 services 裡。D B 多了 healthcheck 的設定,每十秒檢查一次,逾時五秒,最多重試五次,另外給三十秒的啟動緩衝。app 這邊的條件,則寫成等 D B 健康。", "item": 2 },
   { "say": "條件還有另外兩種。一種是只要啟動就好,這是預設的行為。另一種是等一次性的工作成功跑完,例如資料庫遷移。", "item": 2 }
  ],
  "環境變數、健康檢查、啟動順序與 secrets#7": [
   { "say": "這個單元最後,是重啟策略和資源限制。", "item": 0 },
   { "say": "其中記憶體和 C P U 的限制,是 Compose 支援的簡寫,效果等同 docker run 的 memory 和 C P U S 選項。在新的規格裡,也可以寫在 deploy 底下的資源限制區塊。", "item": 1 },
   { "say": "restart 設成 unless stopped,意思是除非你手動把它停掉,不然容器掛了,或是主機重開機,都會自動再起來。", "item": 2 },
   { "say": "mem limit 這一行,把記憶體上限設在五百一十二 M B。", "item": 3 },
   { "say": "C P U S 設成零點五,代表最多只能用半顆處理器。", "item": 4 }
  ],
  "設計多服務應用:架構與維運要點#1": [
   { "say": "第三個單元,我們來設計一個典型的三層應用。使用者先連到 proxy,也就是 engine X,它再轉給 app,你的程式,app 再去連 D B。先看 compose 檔裡幾個關鍵的設定。", "item": 0 },
   { "say": "proxy 把主機的八十號埠,對應到自己的八十號埠,它是唯一對外的入口。", "item": 1 },
   { "say": "proxy 還用唯讀的方式,掛進一份 engine X 的設定檔。", "item": 2 },
   { "say": "它依賴 app 這個服務,所以會在 app 之後啟動。", "item": 3 },
   { "say": "app 自己的根檔案系統設成唯讀,只另外給它一個放在記憶體裡的暫存目錄。", "item": 4 },
   { "say": "而 D B 的資料,放在 D B data 這個具名 volume 裡,容器重建也不會不見。", "item": 5 }
  ],
  "設計多服務應用:架構與維運要點#2": [
   { "say": "這份設計裡的每一個決定都有原因,我們逐項說明。", "item": 0 },
   { "say": "第一,只有 proxy 發布埠。app 和 D B 都不對主機開放,外面的人碰不到它們。", "item": 1 },
   { "say": "第二,用了兩個網路。proxy 只在 frontend,D B 只在 backend,而且 backend 設成 internal,是純內部的網路。app 同時接在兩邊,當作橋樑。這就是分層網路的做法。", "item": 2 },
   { "say": "第三,D B 的資料放在具名 volume,機密則用 secrets。密碼不會出現在 compose 檔、映像檔,或是環境變數的清單裡。", "item": 3 },
   { "say": "第四,app 設成唯讀,再用 T M P F S 提供暫存目錄,縮小被入侵之後可以寫入的範圍。如果你的應用需要寫其他目錄,就要另外規劃。", "item": 4 }
  ],
  "設計多服務應用:架構與維運要點#3": [
   { "say": "還有兩點。", "item": 0 },
   { "say": "第五,所有服務都加上 restart unless stopped,主機重開機之後會自動恢復。", "item": 1 },
   { "say": "第六,app 要等 D B 健康之後才啟動,用的就是上一個單元學的健康檢查條件。", "item": 2 }
  ],
  "設計多服務應用:架構與維運要點#4": [
   { "say": "對照一下檔案的結構。", "item": 0 },
   { "say": "流量的方向是,使用者到 proxy,proxy 到 app,app 再到 D B,一層一層往後。", "item": 1 },
   { "say": "檔案第一行用 name,把專案命名為 notes。", "item": 2 },
   { "say": "接著 services 底下,依序定義 proxy、app 和 D B 三個服務。這份檔案比較長,請依自己的需求調整,密碼檔也要自己建立。", "item": 3 }
  ],
  "設計多服務應用:架構與維運要點#5": [
   { "say": "檔案的後半段,是三個最上層的區塊。", "item": 0 },
   { "say": "secrets,宣告兩個機密,一個是應用程式用的資料庫密碼,一個是 root 密碼,分別來自 secrets 目錄底下的兩個文字檔。", "item": 1 },
   { "say": "volumes,宣告 D B data。", "item": 2 },
   { "say": "networks,宣告 frontend 和 backend,其中 backend 多了一行 internal 設為 true。", "item": 3 }
  ],
  "設計多服務應用:架構與維運要點#6": [
   { "say": "最後是 engine X 設定檔的核心部分。", "item": 0 },
   { "say": "server 區塊裡,監聽八十號埠,然後把所有請求用 proxy pass 轉給 app 的八千號埠,同時把原本的主機名稱和來源 I P,透過標頭一起帶過去。", "item": 1 },
   { "say": "重點是,proxy pass 裡寫的 app,就是 Compose 的服務名稱,由 Docker 內建的 D N S 來解析,所以不需要知道任何 I P。", "item": 2 }
  ],
  "設計多服務應用:架構與維運要點#7": [
   { "say": "最後談擴充副本。", "item": 0 },
   { "say": "要注意,如果 app 設了固定的容器名稱,或是有固定的主機埠對應,就沒辦法擴充,因為名稱和埠都會衝突。", "item": 1 },
   { "say": "擴充的方式,是在 docker compose up 後面加上兩個減號 scale,指定 app 要三個副本。", "item": 2 },
   { "say": "副本變多之後,通常需要反向代理來分配流量。單機上簡單的情況 Compose 做得到,但是複雜的自動擴縮和高可用,就是 Kubernetes 的領域了。", "item": 2 }
  ],
  "closing": [
   { "say": "這一章就到這裡。你已經會用 compose 檔描述多個服務,知道怎麼處理變數和機密、怎麼用健康檢查控制啟動順序,也看過一個三層應用的完整設計。", "item": 0 },
   { "say": "接下來,請到實作練習親手操作一次,再完成章末小測驗,看看自己學會了多少。我們下一章見!", "item": 1, "pause": 1 }
  ]
 }
}
