Azure Static Web Appsでmkdocsをデプロイ

Azure Static Web AppsはSPAや静的HTMLのホスティングを実現するマネージド・サービスである. デプロイするアプリケーションの例には,Next.jsやVuePress,Hugoがある. このサービスを利用することで開発者は,ソースコードから静的HTMLのビルド,デプロイを一貫して行える. 同様のサービスには,AWS AmplifyやFirebase, Cloudflare Pagesがある.

Azure Static Web Appsを使う利点の1つは,GitHubリポジトリとの連携である.通常,こうした静的サイトのホスティングには次の手順をとる.

  1. GitHubリポジトリにあるソースコードをGitHub Actionsに代表されるCIでビルドする.
  2. CIでビルドした成果物をパブリッククラウドのAPIを介してデプロイする.

このとき,開発者はパブリッククラウドのAPIを呼び出すためにアカウントやIAM(Identity and Access Management) Roleを設定する必要がある. IAMを必要最小限かつ適切に設定することは,パブリッククラウドの利用に不慣れな開発者にとって負担の1つである. Azure Static Web Appsを使うことで,開発者はこうしたアカウントの作成やIAMを設定することなく,ソースコードから静的HTMLのビルド,デプロイを一貫して行える.

以降ではmkdocsで作成された静的HTMLで構成されたWebサイトを公開する手順を紹介する. mkdocsはPython製の静的サイトジェネレータである. Markdownファイルを作成し,コマンドを実行するだけでWebサイトを構築できる.

mkdocsのデプロイ手順

(1) Azureのコンソールへアクセスする.ページ上部の検索ボックスに static と入力し,「静的Webアプリ」を選ぶ.

(2) 静的Webアプリの「作成」選ぶ.

(3) 静的Webアプリの詳細を入力する.

  • 名前: sample-app1
  • ホスティングプラン
    • プランの種類: Free: 趣味または個人的なプロジェクト用
  • Azure Functionとステージングの詳細
    • Azure Function APIとステージング環境のリージョン: Central US
  • デプロイの詳細
    • ソース: GitHub
    • 組織: デプロイ対象のGitHubアカウントを選ぶ.
    • リポジトリ: デプロイ対象のGitHubリポジトリを選ぶ.
    • 分岐: デプロイ対象のブランチを選ぶ.
  • ビルドの詳細
    • アプリの場所: /
    • APIの場所:
    • 出力先: /site

FreeのプランはAzureの無料枠で使える.Standardのプランは静的Webアプリ1つにつき定額の課金がされる.無料枠の詳細や条件は以下のURLより確認できる.

Static Web Apps | Microsoft Azure

2023/02/14の段階では以下の仕様が無料枠で提供されている.

  • 料金: Free
  • ネットワーク帯域幅: 100GB
  • カスタムドメイン: アプリあたり2つ
  • SSL証明書: Free
  • デプロイごとの最大ストレージサイズ: 0.25GB
  • SLA: なし

(4) 「確認および作成」を選びデプロイする.以下のデプロイ完了画面が表示されればよい.

(5) 手順(3)で指定したGitHubリポジトリにアクセスする..github/workflows/ に配置されたYAMLファイルを開く.このYAMLファイルはGitHub Actionsを使い,Azureにmkdocsをデプロイするための構成ファイルである.

(6) 構成ファイルに設定をmkdocs用の設定を追記する.なおrequirements.txtにはmkdocsに必要なパッケージの一覧が格納されている.

      - uses: actions/checkout@v2
        with:
          submodules: true
      # 追記ここから
      - uses: actions/setup-python@v4
        with:
          python-version: "3.10"
      - run: |
          pip install -r requirements.txt
          mkdocs build          
      # 追記ここまで
      - name: Build And Deploy
        id: builddeploy
        uses: Azure/static-web-apps-deploy@v1

設定の全体を以下に示す.

name: Azure Static Web Apps CI/CD

on:
  push:
    branches:
      - master
  pull_request:
    types: [opened, synchronize, reopened, closed]
    branches:
      - master

jobs:
  build_and_deploy_job:
    if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.action != 'closed')
    runs-on: ubuntu-latest
    name: Build and Deploy Job
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: true
      - uses: actions/setup-python@v4
        with:
          python-version: "3.10"
      - run: |
          pip install -r requirements.txt
          mkdocs build          
      - name: Build And Deploy
        id: builddeploy
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_KIND_TREE_0C3F0D110 }}
          repo_token: ${{ secrets.GITHUB_TOKEN }} # Used for Github integrations (i.e. PR comments)
          action: "upload"
          ###### Repository/Build Configurations - These values can be configured to match your app requirements. ######
          # For more information regarding Static Web App workflow configurations, please visit: https://aka.ms/swaworkflowconfig
          app_location: "/" # App source code path
          api_location: "" # Api source code path - optional
          output_location: "site" # Built app content directory - optional
          ###### End of Repository/Build Configurations ######

  close_pull_request_job:
    if: github.event_name == 'pull_request' && github.event.action == 'closed'
    runs-on: ubuntu-latest
    name: Close Pull Request Job
    steps:
      - name: Close Pull Request
        id: closepullrequest
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_KIND_TREE_0C3F0D110 }}
          action: "close"

構成ファイルを変更し,GitHubにPushする.

(7) AzureのWebコンソールへ移動し,静的Webアプリからsample-app1を選ぶ.左メニューの「概要」を選び,ページ右端にあるURLをクリックする.このURLが静的HTMLのエンドポイントURLになる.

(8) 必要に応じて左メニューの「カスタムドメイン」から設定を行うことで,独自ドメインでのホストとSSL証明書の発行を行える.