Docker: 使用 GitHub Actions 部署

學習如何利用 GitHub Actions 部署您的 Docker 容器

👋 歡迎來到 Stackhero 文件！

Stackhero 提供一個即用型的 Docker cloud CaaS (Containers as a Service) 解決方案，帶來多種好處，包括：

只需 docker-compose up 即可 輕鬆將 您的容器 部署到生產環境。

可自訂的域名，並使用 HTTPS 保護（例如，https://api.your-company.com，https://www.your-company.com，https://backoffice.your-company.com）。

由 專用的私人 VM 提供的最佳性能和強大的 安全性。

只需點擊一下即可輕鬆更新。

節省時間 並 簡化您的生活：只需 5 分鐘 即可嘗試 Stackhero 的 Docker CaaS cloud hosting 解決方案，並將您的容器部署到生產環境！

GitHub Actions 讓您輕鬆自動化工作，例如將 Docker 容器部署到生產伺服器。這份指南會帶您了解如何安全且可靠地設定 GitHub Actions，將您的 Docker 容器部署到測試（staging）及生產（production）環境。

在這個設定中，您會維護兩個分支：staging 和 production。每當您將程式碼推送到這兩個分支其中之一時，系統就會自動部署到對應的 Stackhero 實例。

擁有 staging 實例並非強制。您可以只用生產實例來跟隨本指南。不過，為了降低風險並提升生產部署的信心，強烈建議同時設有 staging 及 production 實例。這是業界標準及最佳實踐，有助於避免許多潛在問題。

在開始之前，請確保您已擁有 GitHub 帳戶及一個存放您程式碼的 repository。

建立 Docker 服務

首先，請登入您的 Stackhero 控制台，並建立兩個 Stackhero 服務，一個用於 staging，一個用於 production。為了方便管理及減少錯誤，建議將這兩個服務分別命名為「Staging」及「Production」。

還未有 Stackhero 帳戶？您可以在兩分鐘內免費註冊，然後只需幾個步驟即可建立您的 Docker cloud 服務。

Docker 服務範例

設定環境變數及密鑰

取得網域名稱及證書密碼

為了讓 GitHub Actions 能連接到您的 Stackhero Docker 服務，您需要兩項資訊：服務的網域名稱及證書密碼。

在 Stackhero 控制台，選擇您的「production」Docker 服務，然後點擊「Configure」按鈕。

取得服務設定
複製「Domain name」及「Docker certificates password」，以便於後續步驟使用。

取得服務設定

在 GitHub 設定網域名稱及證書密碼

在 GitHub，打開您的專案。
前往 Settings > Environments，然後點擊 New environment。

設定 GitHub 環境
在 Name 欄位輸入「production」並確認。

設定環境名稱
點擊 No restriction 按鈕，選擇 Selected branches and tags。

設定環境限制
點擊 Add deployment branch or tag rule，在 Name pattern 欄位輸入「production」，然後點擊 Add rule。

設定環境分支設定環境分支
在 Environment secrets 下，點擊 Add secret。

新增密鑰
密鑰名稱請用 STACKHERO_CERTIFICATES_PASSWORD，並將您的證書密碼貼到 Value 欄位。

設定證書密碼密鑰
在 Environment variables 下，點擊 Add variable。

設定變數
名稱請用 STACKHERO_ENDPOINT，並將您的 Docker 服務 endpoint 貼到 Value 欄位。您可以在 Stackhero 控制台找到這個 endpoint。

設定 endpoint 變數

如果您自訂了服務的網域名稱，請記得使用您的自訂網域，而不是 <XXXXXX>.stackhero-network.com。

自訂 Docker Compose 設定檔

如果您的 docker-compose.yml 已經在專案根目錄，且不需要特別自訂，可以略過本節。

預設情況下，GitHub Actions 會在專案根目錄尋找 docker-compose.yml。如果您需要使用其他檔案或自訂設定，可以調整部署指令。例如，若您使用我們的 Node.js 與 Docker 入門範本，可以新增一個名為 STACKHERO_DEPLOY_COMMAND 的環境變數，並設為：

docker compose --env-file env.list --file docker/docker-compose.yml --file docker/docker-compose.production.yml up --build --remove-orphans -d

設定 GitHub Actions workflow

在本機，進入您的 Git repository，建立一個 .github/workflows 目錄。在此目錄下建立一個名為 deploy-to-stackhero.yml 的檔案，內容如下：

# File: .github/workflows/deploy-to-stackhero.yml

name: Deploy to Stackhero
description: Deploy branch "${{ github.ref_name }}" to Stackhero

on:
  push:
    # 這些分支在 push 時會觸發部署動作。
    # 請確保在 GitHub（Settings > Environments）建立與分支名稱相符的環境。
    # 並在該環境中新增密鑰 STACKHERO_CERTIFICATES_PASSWORD 及變數 STACKHERO_ENDPOINT。
    branches: [ "production", "staging" ]

jobs:
  Deploy:
    environment: ${{ github.ref_name }}
    runs-on: ubuntu-latest
    steps:
    - uses: stackhero-io/github-actions-deploy-docker-containers-to-stackhero@v1
      with:
        # 密鑰 STACKHERO_CERTIFICATES_PASSWORD 及變數 STACKHERO_ENDPOINT 應在對應分支的 GitHub 環境中設定。
        certificates_password: ${{ secrets.STACKHERO_CERTIFICATES_PASSWORD }}
        endpoint: ${{ vars.STACKHERO_ENDPOINT }}
        # deployment_command 為選用項目。如需自訂 Docker Compose 指令可使用。
        deployment_command: ${{ vars.STACKHERO_DEPLOY_COMMAND }}

您可以用以下指令提交變更：

git add -A .
git commit -m "Add GitHub Actions to deploy to Stackhero"

若要建立 production 分支，請執行：

git checkout -b production

然後將 production 分支推送到 GitHub：

git push --set-upstream origin production

當您的程式碼推送後，GitHub Actions 會自動將其部署到您的 production Stackhero 實例。您可以在 GitHub 專案的 Actions 分頁監察部署進度。

GitHub Actions 已部署到 production

就是這麼簡單。您現在已設定好利用 GitHub Actions 自動部署程式碼到生產環境。

建立 staging 環境

staging 環境的設定步驟與 production 相同。只需重複上述流程，將 production 換成 staging 即可。

然後，建立 staging 分支：

git checkout -b staging

並將 staging 分支推送到 GitHub：

git push --set-upstream origin staging

完成後，GitHub Actions 會自動將 staging 分支部署到指定的 Docker staging 實例。

在 docker-compose.yml 使用環境變數

您可以在 GitHub 專案中定義環境變數，這些變數會在 docker-compose.yml 內部可用。這對於需要部署到不同網域（例如 staging.my-company.com 用於 staging，my-company.com 用於 production）特別有用。

在 GitHub，前往 Settings > Environments，建立名為 WEBSITE_DOMAIN 的環境變數。
對於 staging 環境，將 WEBSITE_DOMAIN 設為「staging.my-company.com」。
對於 production 環境，將 WEBSITE_DOMAIN 設為「my-company.com」。

接著，更新 .github/workflows/deploy-to-stackhero.yml，將 WEBSITE_DOMAIN 變數傳遞給 Stackhero GitHub Action：

name: Deploy to Stackhero
description: Deploy branch "${{ github.ref_name }}" to Stackhero

on:
  push:
    branches: [ "production", "staging" ]

jobs:
  Deploy:
    environment: ${{ github.ref_name }}
    runs-on: ubuntu-latest
    steps:
    - uses: stackhero-io/github-actions-deploy-docker-containers-to-stackhero@v1
      with:
        certificates_password: ${{ secrets.STACKHERO_CERTIFICATES_PASSWORD }}
        endpoint: ${{ vars.STACKHERO_ENDPOINT }}
        deployment_command: ${{ vars.STACKHERO_DEPLOY_COMMAND }}
      env:
        WEBSITE_DOMAIN: ${{ vars.WEBSITE_DOMAIN }}

然後，更新您的 docker-compose.yml，將硬編碼的網域名稱改為使用 WEBSITE_DOMAIN 變數：

services:
  test:
    image: nginx
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.test.rule=Host(`${WEBSITE_DOMAIN}`)" # 使用 WEBSITE_DOMAIN 環境變數作為網域名稱。
      - "traefik.http.routers.test.tls.certresolver=letsencrypt"

進階建議

建議保護 production 及 staging 分支，以避免直接推送。啟用分支保護後，所有變更都需經 pull request，由具備權限的人員審核及合併。這樣可以確保功能先在 staging 平台驗證，經批准後才推送到 production。

遵循這個 workflow，您可以同時確保安全性（只有授權團隊成員能部署到 staging 及 production）及可靠性（新功能會先在 staging 測試，才會部署到生產環境）。