{
 "byKey": {
  "cover": [
   { "say": "大家好,歡迎回到容器管理與應用。前兩章我們用的都是別人做好的映像檔,這一章要自己動手做。我們會學怎麼寫 Dockerfile、用 docker build 建置映像檔,最後實際把 Python 和 Node 的應用程式包起來。", "item": 0 }
  ],
  "Dockerfile 基本指令與 docker build#1": [
   { "say": "先來認識 Dockerfile 是什麼。", "item": 0 },
   { "say": "它是一個純文字檔,用一行一行的指令,描述怎麼一步一步做出一個映像檔。", "item": 1 },
   { "say": "有了它,建置的過程就變成程式碼,可以放進版本控制,任何人在任何機器上,都能做出一模一樣的映像檔。這就是大家常說的,基礎設施即程式碼的精神。", "item": 1 }
  ],
  "Dockerfile 基本指令與 docker build#2": [
   { "say": "我們從一個最小的例子開始。假設有一支 Python 小程式,叫 app 點 P Y,我們用四行的 Dockerfile 把它包起來,再建置和執行。內容在下一頁,這裡先說明三個重點。", "item": 0 },
   { "say": "第一,docker build 會去讀指定目錄裡的 Dockerfile。指令最後面那一個點,代表目前的目錄,它就是所謂的建置情境,英文叫 build context。", "item": 1 },
   { "say": "第二,減號 T 是幫做出來的映像檔取名字,順便標上版本。", "item": 2 },
   { "say": "第三,build context 是 Docker 會整包送給 daemon 的目錄內容。所以 COPY 指令,只能複製這個目錄裡面的檔案。", "item": 3 }
  ],
  "Dockerfile 基本指令與 docker build#3": [
   { "say": "我們一行一行來看這個 Dockerfile。", "item": 0 },
   { "say": "第一行 FROM,指定基底映像檔,這裡用的是 python 三點一二 slim。", "item": 1 },
   { "say": "第二行 WORKDIR,把工作目錄設定在斜線 app。", "item": 2 },
   { "say": "第三行 COPY,把 app 點 P Y 複製到工作目錄裡。", "item": 3 },
   { "say": "第四行 C M D,指定容器啟動的時候,要用 python 執行這支程式。", "item": 4 },
   { "say": "寫好之後就用 docker build 來建置,加上減號 T,把映像檔命名為 hello 減號 P Y,版本一點零,最後別忘了那個點。", "item": 5 }
  ],
  "Dockerfile 基本指令與 docker build#4": [
   { "say": "建置完成,就可以執行了。", "item": 0 },
   { "say": "用 docker run 加上兩個減號 R M,跑我們剛做好的映像檔,程式執行完,容器就會自動刪除。", "item": 1 }
  ],
  "Dockerfile 基本指令與 docker build#5": [
   { "say": "接下來把最常用的指令整理一遍。順帶一提,指令名稱習慣用大寫,其實大小寫都可以,而井字號開頭的是註解。", "item": 0 },
   { "say": "FROM 用來指定基底映像檔,每個 Dockerfile 都是以它開頭。請用具體的 tag,像剛才的三點一二 slim,不要用 latest。", "item": 1 },
   { "say": "WORKDIR 是設定後面指令的工作目錄,目錄不存在的話會自動建立。它比在 RUN 裡面切換目錄可靠,因為每一個 RUN 都是獨立的 shell,切過去的目錄不會保留到下一行。", "item": 2 },
   { "say": "COPY 後面接來源和目的,把 build context 裡的檔案複製進映像檔。", "item": 3 }
  ],
  "Dockerfile 基本指令與 docker build#6": [
   { "say": "繼續看下一組。", "item": 0 },
   { "say": "RUN 是在建置的時候執行指令,並且把結果存成新的一層,最常用來安裝套件。", "item": 1 },
   { "say": "E N V 是設定環境變數,建置的時候和執行的時候都有效,而且會保留在映像檔裡面。", "item": 2 },
   { "say": "A R G 是建置參數,只在建置的時候有效,用 build arg 這個選項從外面傳進來。", "item": 3 }
  ],
  "Dockerfile 基本指令與 docker build#7": [
   { "say": "再來五個。", "item": 0 },
   { "say": "EXPOSE 是宣告容器預計會監聽哪一個埠。要注意,它只是文件說明,不會真的對外開放,要發布還是得用減號 P。", "item": 1 },
   { "say": "USER 是指定後面的指令,要用哪一個使用者的身分來執行。", "item": 2 },
   { "say": "C M D 是容器啟動時預設執行的指令,它可以被 docker run 後面接的指令蓋掉。", "item": 3 },
   { "say": "ENTRYPOINT 是容器固定的進入點,下一個單元會仔細說明。", "item": 4 },
   { "say": "HEALTHCHECK 則是定義怎麼檢查容器健不健康,第八章會用到。另外還有 LABEL,可以替映像檔加上維護者、版本這類說明資料。", "item": 5 }
  ],
  "CMD、ENTRYPOINT、ENV、ARG 與 .dockerignore#1": [
   { "say": "進入第二個單元。C M D 和 ENTRYPOINT 都是決定容器啟動時要執行什麼,差別在於能不能被覆蓋,還有怎麼組合。", "item": 0 },
   { "say": "C M D 提供的是預設的指令或參數。只要你在 docker run 的映像檔名稱後面,多寫了其他指令,C M D 就會整個被取代。", "item": 1 },
   { "say": "ENTRYPOINT 是固定的執行檔。docker run 後面多寫的內容,會被當成參數接在它後面。想要取代它,要用 entrypoint 這個選項才行。", "item": 2 },
   { "say": "兩個可以組合起來用。像這個例子,ENTRYPOINT 固定是用 python 執行 app 點 P Y。", "item": 3 },
   { "say": "C M D 則提供預設的參數,把 port 設成八千。如果執行的時候自己在後面寫 port 九千,就只會換掉參數的部分。", "item": 4 },
   { "say": "怎麼選呢?簡單的服務,只用 C M D 就夠了。想把映像檔做成像一個指令工具,固定就是跑某一支程式,才需要用 ENTRYPOINT。", "item": 4 }
  ],
  "CMD、ENTRYPOINT、ENV、ARG 與 .dockerignore#2": [
   { "say": "C M D 有兩種寫法,一種叫 exec 形式,一種叫 shell 形式。", "item": 0 },
   { "say": "建議用 exec 形式。因為這樣程式會直接成為容器的一號程序,docker stop 送出停止訊號的時候,它收得到,就能好好地收尾、優雅結束。", "item": 1 },
   { "say": "exec 形式的樣子,是用中括號包起來的 JSON 陣列,每個字各自用引號括起來。", "item": 2 },
   { "say": "shell 形式則是直接把指令寫出來,實際上它會交給 S H 去執行。這時候一號程序是 S H,訊號可能到不了你的程式,結果 docker stop 要等十秒逾時,再被強制砍掉。", "item": 3 },
   { "say": "要注意,exec 形式不經過 shell,所以不會幫你展開環境變數,也不能用管線。真的需要的話,可以明確呼叫 S H 加減號 C,並且用 exec 開頭來啟動主程式。", "item": 3 }
  ],
  "CMD、ENTRYPOINT、ENV、ARG 與 .dockerignore#3": [
   { "say": "接下來是 COPY 和 ADD,這兩個都能把檔案放進映像檔。", "item": 0 },
   { "say": "COPY 很單純,就是複製 context 裡面的檔案或目錄,行為很明確,請優先使用。", "item": 1 },
   { "say": "ADD 除了複製,還會自動解壓縮本機的 tar 檔,也能從網址下載。這些魔法反而容易造成意外,所以建議只有在需要自動解壓縮的時候才用,其他情況一律用 COPY。", "item": 2 }
  ],
  "CMD、ENTRYPOINT、ENV、ARG 與 .dockerignore#4": [
   { "say": "再來比較 E N V 和 A R G。", "item": 0 },
   { "say": "E N V 會寫進映像檔,容器執行的時候裡面也看得到,而且可以用 docker run 的減號 E 來覆蓋。", "item": 1 },
   { "say": "A R G 只存在於建置期間,建置完成之後,執行環境就看不到了。但是請注意,它的值還是可能留在映像檔的建置歷史裡面。", "item": 2 },
   { "say": "所以有一條很重要的安全規則。不要用 E N V 或 A R G 來傳密碼、A P I 金鑰或 token。任何拿到映像檔的人,用 docker history 和 docker inspect 都看得到。", "item": 2 },
   { "say": "正確的做法是執行的時候才注入,像是環境變數、secret 或是掛載檔案。建置時需要的機密,則用 BuildKit 的 secret mount,第七章會介紹。", "item": 2 }
  ],
  "CMD、ENTRYPOINT、ENV、ARG 與 .dockerignore#5": [
   { "say": "這個單元的最後,是點 dockerignore 這個檔案。它放在 context 的根目錄,語法和點 gitignore 很像,用來控制哪些東西不要送進 build context。它有三個作用。", "item": 0 },
   { "say": "第一是加快建置。不需要的東西就不要送給 daemon,像是 node modules 和點 git 這些很肥的目錄。", "item": 1 },
   { "say": "第二是避免洩漏。點 E N V、私鑰和本機的設定檔,都不應該被 COPY 整個目錄的時候一起帶進映像檔。", "item": 2 },
   { "say": "第三是提高快取的命中率。無關的檔案有變動,就不會讓 COPY 那一層的快取失效。", "item": 3 },
   { "say": "如果沒有寫這個檔案,又直接複製整個目錄,點 E N V 這種檔案就會被打包進去。一旦映像檔推到公開的 registry,機密就外洩了。這是非常常見的資安事故,請一定要小心。", "item": 3 }
  ],
  "CMD、ENTRYPOINT、ENV、ARG 與 .dockerignore#6": [
   { "say": "來看一份範例,一行寫一個要排除的項目。", "item": 0 },
   { "say": "點 git,版本控制的資料夾。", "item": 1 },
   { "say": "點 E N V,裡面通常放著密碼和金鑰。", "item": 2 },
   { "say": "星號點 log,所有的日誌檔。", "item": 3 },
   { "say": "node modules,Node 的套件目錄。", "item": 4 },
   { "say": "Python 的快取目錄,pycache。", "item": 5 },
   { "say": "還有 Dockerfile 本身,映像檔裡面並不需要它。", "item": 6 }
  ],
  "CMD、ENTRYPOINT、ENV、ARG 與 .dockerignore#7": [
   { "say": "最後還有一項。", "item": 0 },
   { "say": "就是點 dockerignore 自己,它也不需要被包進映像檔。", "item": 1 }
  ],
  "實戰:容器化應用與多階段建置#1": [
   { "say": "好,第三個單元我們來實戰,第一個例子是 Python 的網站應用。專案裡有程式本身、列出套件的 requirements 檔、Dockerfile,還有點 dockerignore。先講四個重點,等一下再逐行看內容。", "item": 0 },
   { "say": "第一,設定 python unbuffered 這個環境變數,讓 Python 的輸出立刻寫到標準輸出,這樣 docker logs 才能即時看到。", "item": 1 },
   { "say": "第二,pip 安裝的時候加上 no cache dir 這個選項,避免 pip 的快取留在映像檔裡,可以縮小體積。", "item": 2 },
   { "say": "第三,用非 root 的使用者來執行,萬一被入侵,危害會小很多。", "item": 3 },
   { "say": "第四,服務一定要綁定在全零的位址,也就是所有網路介面。如果只綁在本機位址,容器外面的流量,包含減號 P 對應進來的,通通連不進來。這是新手最常遇到的,容器起來了卻連不上的原因。", "item": 4 }
  ],
  "實戰:容器化應用與多階段建置#2": [
   { "say": "我們從專案的內容開始看。", "item": 0 },
   { "say": "專案目錄叫 my app,裡面就是剛剛說的四個檔案。", "item": 1 },
   { "say": "requirements 檔裡面,第一個套件是 flask,而且把版本固定住。", "item": 2 },
   { "say": "第二個是 gunicorn,同樣固定版本。版本寫死,建置的結果才能重現。", "item": 3 },
   { "say": "接著是 Dockerfile。第一行 FROM,以 python 三點一二 slim 當作基底。", "item": 4 }
  ],
  "實戰:容器化應用與多階段建置#3": [
   { "say": "繼續往下。", "item": 0 },
   { "say": "用 E N V 設定兩個環境變數。一個是叫 Python 不要產生位元組碼的快取檔,另一個就是剛剛說的 unbuffered,讓輸出不要被緩衝。", "item": 1 },
   { "say": "WORKDIR 把工作目錄設在斜線 app。", "item": 2 },
   { "say": "然後先只複製 requirements 這一個檔案進去。", "item": 3 }
  ],
  "實戰:容器化應用與多階段建置#4": [
   { "say": "接下來是兩個 RUN。", "item": 0 },
   { "say": "第一個用 pip install 安裝 requirements 裡列的套件,並且加上不留快取的選項。", "item": 1 },
   { "say": "第二個是建立一個系統群組和一個系統使用者,名字都叫 app,而且不建立家目錄。等一下就要用這個身分來跑程式。", "item": 2 }
  ],
  "實戰:容器化應用與多階段建置#5": [
   { "say": "Dockerfile 的最後四行。", "item": 0 },
   { "say": "COPY 點 點,把專案其餘的檔案全部複製進來。", "item": 1 },
   { "say": "USER app,從這裡開始切換成剛剛建立的非 root 使用者。", "item": 2 },
   { "say": "EXPOSE 八千,宣告這個服務會監聽八千號埠。", "item": 3 },
   { "say": "最後用 C M D 啟動 gunicorn。因為 gunicorn 預設只綁本機位址,所以這裡用 bind 選項,明確指定綁在全零位址的八千號埠。", "item": 4 }
  ],
  "實戰:容器化應用與多階段建置#6": [
   { "say": "寫好之後,建置並且執行看看。", "item": 0 },
   { "say": "用 docker build 加減號 T,把映像檔命名為 my app,版本一點零。", "item": 1 },
   { "say": "用 docker run 在背景啟動,容器取名 my app,並且把主機的八千號埠對應到容器的八千號埠。", "item": 2 },
   { "say": "最後用 curl 連本機的八千號埠,有收到回應,就代表我們的應用成功容器化了。", "item": 3 }
  ],
  "實戰:容器化應用與多階段建置#7": [
   { "say": "第二個例子是 Node J S 的應用,寫法的結構很像。以 node 二十二 alpine 為基底,先複製 package 和 lock 兩個檔案、安裝套件,再複製其餘的程式,最後用 node 啟動 server。", "item": 0 },
   { "say": "這裡安裝套件用的是 N P M C I。它會依照 lock 檔精確安裝,比 N P M install 更適合用在建置。", "item": 1 },
   { "say": "另外,官方的 node 映像檔已經內建一個叫 node 的非 root 使用者,所以直接寫 USER node 就可以,不用自己建立。", "item": 2 }
  ],
  "closing": [
   { "say": "這一章就到這裡。你已經會寫 Dockerfile、分得清楚 C M D 和 ENTRYPOINT、知道機密不能寫進映像檔,也看過完整的容器化範例了。", "item": 0 },
   { "say": "接下來,請到實作練習親手操作一次,再完成章末小測驗,看看自己學會了多少。我們下一章見!", "item": 1, "pause": 1 }
  ]
 }
}
