🔧

AWS CodeSuite による Sphinx ドキュメントの CI/CD

2022/03/23に公開

AWS

はじめに

a. 記事概要

本記事では、AWS CodeSuite を利用して Sphinx ドキュメントの CI/CD を実装します。

Git リポジトリ上で管理された Sphinx ソースを編集し、GitHub における main ブランチへのマージをトリガとして、ビルドパイプラインを実行します。
ビルドパイプラインでは、Sphinx ソースをビルドし、そのアーティファクトを S3 にデプロイします。ビルドには CodeBuild を利用します。
デプロイした Sphinx ドキュメントを静的ウェブサイトホスティングで公開してみます。

b. 前提条件

利用する AWS アカウントにおいて、手順実施に必要な権限を有していること
AWS IAM にて、GitHub からアクセスするための OIDC 設定が完了していること

OIDC の設定については、以下の記事などを参考にしてください。

c. リソース

本記事で使用するリソースは、GitHub に公開しています。

roki18d / sphinx-sample-docs | GitHub

1. 実施手順

1-1. デプロイ先 S3 バケットの作成

ビルドされた Sphinx ドキュメントをデプロイするための S3 バケットを作成します。バケット名は任意ですが、ここでは sphinx-sample-docs.roki18d.io としておきます。

1-2. buildspec.yml の作成

CodeBuild で利用される buildspec.yml を作成します。buildspec.yml は、ビルドコマンド群やそれらに関連する設定を定義しておくためのファイルです。例えば、以下のように記述します。

buildspec.yml

version: 0.2

phases:
  install:
    runtime-versions:
      python: 3.9
    commands:
      # OS
      - apt -y update
      - apt -y install graphviz fonts-ipafont plantuml
      # Python
      - pip install --upgrade pip
      - pip install -r requirements.txt
  build:
    commands:
      - sphinx-build -b html source build
artifacts:
  files:
    - "**/*"
  base-directory: "build/"

1-3. CodeBuild プロジェクトの作成

任意のリソース名で、以下のような仕様の CodeBuild プロジェクトを作成します。

① Source

Source Provider ... GitHub
Repository ... roki18d/sphinx-sample-docs - 自身のリポジトリ
Source version ... main - ビルド対象とするブランチ名

② Environment

Image ... aws/codebuild/standard:5.0
Environment type ... Linux
Compute ... 3 GB memory, 2 vCPUs
Privileged ... True

③ Buildspec

Buildspec name ... buildspec.yml

④ Artifacts - Primary Artifact

Type ... S3
Bucket name ... sphinx-sample-docs.roki18d.io - 自身の作成したバケット
Name ... / - アーティファクトを含む S3 内のフォルダ名
Artifacts packaging ... None
Disable artifact encryption ... Yes

1-4. CodePipeline パイプラインの作成

任意のリソース名で、以下のような仕様の CodePipeline パイプラインを作成します。

① Source stage

Source provider ... GitHub (Version 2)
Connection ... OIDC 設定で作成された GitHub 接続
Repository name ... roki18d/sphinx-sample-docs - 自身のリポジトリ
Branch name ... main - ビルド対象とするブランチ名
Change detection options:
- Start the pipeline on source code change ... Yes

② Build stage

Build provider ... AWS CodeBuild
Project name ... 作成した CodeBuild プロジェクト

③ Deploy stage

Deploy provider ... Amazon S3
Bucket ... sphinx-sample-docs.roki18d.io - 自身の作成したバケット

1-5. パイプライン実行確認

CodePipeline パイプラインの作成が完了すると、自動的に実行が開始します。

パイプラインの実行完了後、デプロイ先の S3 バケットを見てみると、ビルドされた Sphinx ドキュメントが生成されています。

2. Web 公開

S3 の静的ウェブサイトホスティングの機能を使ってビルドアーティファクトを Web 上に公開してみます。

バケット内に秘匿な情報がないことを確認し、S3 バケットを公開します。

静的ウェブサイトホスティング有効化後、[Bucket website endpoint] に記載の URL にアクセスします。

3. 動作確認

Sphinx ソースを編集し、その変更を main ブランチに Push します。CodePipeline パイプラインが実行されていることを確認します。

パイプライン実行完了後、再度エンドポイント URL にアクセスし、変更が反映されていることを確認します。

さいごに

本記事では AWS CodeSuite を利用して Sphinx ドキュメントの CI/CD を実装してみました。いかがでしたでしょうか。

今回は利用しませんでしたが、CodeBuild プロジェクトでは環境変数を設定し、ビルドの条件を実行ごとに動的に変更することができます。CodePipeline 以外にも Step Functions から呼び出すことができ、EnvironmentVariablesOverride を指定するなどして柔軟にビルドパイプラインを構築できます。

また、今回は静的ウェブコンテンツを公開する簡易な手段として S3 の静的ウェブサイトホスティングを利用しましたが、本格的な配信を実現するには S3 バケットをオリジンとする CloudFront ディストリビューションを構成するのがベターです。これについては機会があればまた別の記事で扱いたいと思います。

最後までご覧頂き、ありがとうございました。