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リポジトリとの連携である．通常，こうした静的サイトのホスティングには次の手順をとる．

GitHubリポジトリにあるソースコードをGitHub Actionsに代表されるCIでビルドする．
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証明書の発行を行える．