Docusaurus・AWS(CloudFront+S3)での高速・安全なサイト公開手順

はじめに

ドキュメントサイトや技術ブログを立ち上げる際、どのフレームワークを選ぶか迷っていませんか？ 近年、その選択肢として大きな注目を集めているのが「Docusaurus」です。

Docusaurusは、簡単な操作性と高いカスタマイズ性を両立した静的サイトジェネレーターで、多くのオープンソースプロジェクトのドキュメントサイトで採用されています。

この記事では、まずDocusaurusが選ばれる理由・メリットを解説し、その後、Docusaurusで構築したサイトをAWSのCloudFrontとS3を利用して「高速・低コスト・安全」に公開する具体的な手順をご紹介します。

そもそもDocusaurusとは？ドキュメントサイト構築に選ばれる4つの理由

DocusaurusはFacebook（現Meta）によって開発された、Reactベースの静的サイトジェネレーターです。なぜ多くの開発者に選ばれるのか、その主なメリットを見ていきましょう。

理由1：Markdownだけで本格的なサイトが書ける

Docusaurusの最大の特徴は、Markdownファイルを書くだけでリッチなドキュメントサイトを構築できる手軽さにあります。エンジニアは普段使い慣れたMarkdownでコンテンツ執筆に集中でき、複雑なWeb制作の知識はほとんど必要ありません。

理由2：標準で豊富な機能が揃っている

ドキュメントサイトに求められる便利な機能が、最初から組み込まれています。

• バージョニング機能: ソフトウェアのバージョンごとにドキュメントを管理できます。
• 多言語対応（i18n）: 翻訳ファイルを用意するだけで、簡単に多言語サイトを構築できます。
• 強力な検索機能: Algolia DocSearchとの連携がスムーズで、ユーザビリティの高い検索機能をすぐに導入できます。
• ブログ機能: ドキュメントだけでなく、技術ブログやお知らせなども同じサイト内で管理できます。

理由3：Reactによる高いカスタマイズ性

サイトの裏側はReactで構築されているため、Web開発の知識があればデザインや機能を自由自在にカスタマイズできます。既成のコンポーネントを組み込んだり、独自のコンポーネントを作成したりと、プロジェクトの要件に応じた柔軟な拡張が可能です。

理由4：静的サイトならではのパフォーマンス

ビルド時に静的なHTML/CSS/JSファイルが生成されるため、サーバーサイドの処理が不要です。これにより、非常に高速なページ表示が実現します。この「静的サイト」という特性が、後述するS3やCloudFrontとの構成と抜群の相性を発揮します。

DocusaurusサイトをCloudFront + S3で公開する3つのメリット

Docusaurusの良さを理解した上で、次はそのサイトを「どのように公開するか」です。AWSのCloudFrontとS3を組み合わせることで、Docusaurusのメリットをさらに引き出すことができます。

メリット1：CDNによる高速なコンテンツ配信 🚀

CloudFrontは、世界中に分散配置されたエッジサーバーにサイトのコンテンツをキャッシュ（一時保存）するCDN（コンテンツデリバリーネットワーク） です。 ユーザーがサイトにアクセスした際、地理的に最も近いエッジサーバーからコンテンツが配信されるため、物理的な距離による遅延が大幅に短縮され、ページの表示速度が劇的に向上します。サイトの表示速度は、ユーザー体験（UX）だけでなくSEO評価にも直結する重要な要素です。

メリット2：高い可用性と耐久性 💪

S3 は、Amazonが「99.999999999% (イレブンナイン)」という非常に高い耐久性を保証しているストレージサービスです。S3にサイトのファイルを保管することで、サーバーダウンなどの心配がほとんどなく、非常に安定したサイト運用が可能になります。

メリッ​​ト3：従量課金制によるコスト最適化 💰

S3とCloudFrontは、どちらも実際に使用した分だけ料金が発生する従量課金制です。アクセスが少ないうちはコストを低く抑えることができ、アクセスが増えた場合も高価なサーバーを契約する必要はありません。サイトの規模に応じてコストが最適化されるため、個人開発から大規模な商用サイトまで幅広く対応できます。

構築前に知っておきたい注意点

非常に強力な構成ですが、Docusaurusサイトを公開する上で特有の注意点があります。事前におさえておきましょう。

注意点1：S3のサブディレクトリ問題

Docusaurusで作成したブログ記事などのページは、https://example.com/blog/my-first-post/ のようなURLとなります。しかし、S3の静的ウェブサイトホスティング機能でこのURLに直接アクセスすると、S3は index.html を自動で補完してくれないため、404エラー（Not Found）となってしまいます。

この問題を解決するため、後述するCloudFront Functionsという機能を使って、リクエストURLを適切に書き換える処理を追加します。

注意点2：キャッシュの更新（Invalidation）

サイトの内容を更新（デプロイ）した際、CloudFrontのエッジサーバーには古いキャッシュが残っているため、すぐには変更が反映されません。変更を即座に反映させるためには、Invalidation（インバリデーション）　という操作を行い、キャッシュを意図的にクリアする必要があります。

【実践】DocusaurusサイトのセットアップからAWSデプロイまでの全手順

ここからは、Docusaurusサイトを実際に構築し、AWS上にデプロイするまでの具体的な手順をステップ・バイ・ステップで解説します。AWSのマネジメントコンソール上での操作が中心です。

ステップ1：Docusaurusプロジェクトの初期セットアップ

まずは、Docusaurusプロジェクトを自身のPCにセットアップするところから始めます。

1. Node.jsとnpm (またはYarn) のインストール

DocusaurusはNode.jsとnpm またはYarnを必要とします。まだインストールしていない場合は、以下のリンクから最新版をインストールしてください。

• Node.js: https://nodejs.org/ja/ (Node.jsパッケージにnpmも含んでいます)
• Yarn: https://yarnpkg.com/ (npmがインストールされていれば、npm install -g yarn でインストールできます)

2. Docusaurusプロジェクトの作成

ターミナルを開き、以下のコマンドを実行して新しいDocusaurusプロジェクトを作成します。my-website の部分は、好きなプロジェクト名に変更してください。

npx create-docusaurus@latest my-website classic

• npx create-docusaurus@latest: Docusaurusの最新版をインストールし、プロジェクトを作成します。
• my-website: 作成されるプロジェクトのディレクトリ名です。
• classic: Docusaurusが提供する「Classic」テンプレートを使用することを意味します。最も一般的なテンプレートです。

問題なく [SUCCESS] Created my-website.が表示されればOK。

3. プロジェクトディレクトリへの移動

プロジェクトが作成されたら、以下のコマンドでそのディレクトリに移動します。

cd my-website

4. ローカルサーバーの起動 (確認用)

プロジェクトディレクトリ内で、以下のコマンドを実行すると、Docusaurusのローカル開発サーバーが起動し、ブラウザでサイトを確認できるようになります。通常は `http://localhost:3000` でサイトが表示されます。

npm run start
# または yarn start

以下のようにDocusaurusのトップページが表示されればOK。

参考
Docusaurus Installation

ステップ2：Docusaurusプロジェクトのビルド

AWSにデプロイするために、Docusaurusサイトの静的ファイルを生成します。プロジェクトのルートディレクトリで、以下のコマンドを実行してください。

npm run build

コマンドが完了すると、プロジェクト内に ./build ディレクトリが作成されます。この中にあるファイル群が、今回S3にアップロードする対象となります。

ステップ3：S3バケットの作成と設定

次に、ビルドしたファイルを格納するS3バケットを用意します。

1. AWSマネジメントコンソールにログインし、サービス一覧から「S3」を検索して選択します。
2. リージョンは、任意の場所（例: 東京リージョン ap-northeast-1）を選択。
3. 「バケットを作成」をクリックします。
4. バケット名を決定します（グローバルで一意となる名前）。
5. その他の設定はデフォルトのままで、「バケットを作成」をクリックします。
   • 「パブリックアクセスをすべてブロック」にチェックが入ったままでOKです。これはS3バケットへの直接的なパブリックアクセスを防ぎ、後ほどCloudFrontからのセキュアなアクセスのみを許可するための重要な設定です。

ステップ4：ビルドしたファイルをS3にアップロード

作成したS3バケットに、先ほど生成した build ディレクトリの中身をアップロードします。

1. 作成したバケットを選択し、「アップロード」をクリックします。
2. build ディレクトリの中にあるファイルとフォルダをすべて、ドラッグ＆ドロップなどでアップロード画面に追加し、「アップロード」を実行します。
   ※build実行をmac で行った場合、.DS_Storeがbuildディレクトリ内に作成されアップロードエラーとなることがあります。不要ファイルのため無視して問題ありません。

ステップ5：CloudFrontディストリビューションの作成

いよいよCloudFrontの設定です。ここでS3とCloudFrontを連携させます。
※以下手順に登場するCloudFront作成画面は2025年6月に発表された新セットアップ画面で行います。旧画面と手順が若干異なりますのでご注意下さい。

1. AWSマネジメントコンソールで「CloudFront」を検索して選択します。
2. 「ディストリビューションを作成」をクリックします。
3. ディストリビューション名 を決定します。
   
4. オリジンの項目で、先ほど作成したS3バケットを選択します。
5. その他の設定はデフォルトを選択します。
   • このOACの設定により、S3バケットへのアクセスを特定のCloudFrontディストリビューションからのみに制限でき、安全性が高まります。くわしくはAmazon S3 オリジンへのアクセスを制限する参照
     
6. AWS WAFは一旦無効としておきます。
   
7. 設定内容を確認したら、ページ下部の「ディストリビューションを作成」をクリックします。作成には数分かかります。
   
8. ディストリビューションを作成すると、対象のS3バケットポリシーが自動更新されます。
   • もし、自動で更新されない場合はオリジンの編集画面から「ポリシーをコピー」をクリックしてポリシー内容を控え、「S3バケットの権限に移動」からバケットポリシーを手動更新してください。
9. 作成後、以下の２点を変更します。変更が反映されるまで数分かかります。
   • ディストリビューションの設定からデフォルトルートオブジェクトに index.html と入力します。これにより、ルートドメイン (https://example.com/`) へのアクセス時にindex.html` を表示させることができます。
   • ビューワーのプロトコルポリシーは「Redirect HTTP to HTTPS」を選択します。

参考
基本的な CloudFront ディストリビューションの開始方法

ステップ6：CloudFront Functionsでリダイレクト設定

次に、本構成のキモであるサブディレクトリ問題を解決します。

1. CloudFrontの管理画面のサイドメニューから「関数」を選択し、「関数を作成」をクリックします。
2. 関数名（例: redirect-for-docusaurus）を入力し、「関数を作成」をクリックします。
   
3. 関数コードのセクションに、以下のコードを貼り付けます。このコードは、リクエストされたURLの末尾が / の場合や拡張子がない場合に index.html を補完する役割を果たします。

   async function handler(event) {
   var request = event.request;
   var uri = request.uri;
   
   // Check whether the URI is missing a file name.
   if (uri.endsWith('/')) {
       request.uri += 'index.html';
   } 
   // Check whether the URI is missing a file extension.
   else if (!uri.includes('.')) {
       request.uri += '/index.html';
   }
   
   return request;
   }
   

   

4. コードを「変更を保存」し、「発行」タブから関数を公開します。
5. 作成したCloudFrontディストリビューションの「ビヘイビア」タブを選択し、デフォルトのビヘイビアを編集します。
6. ページ下部の関数を関連付けるセクションで、ビューワーリクエストの関数として、先ほど作成したCloudFront Functionを選択します。
7. 「変更を保存」します。変更が反映されるまで数分かかります。
   

参考
CloudFront Functions のビューワーリクエストイベントで、ファイル名がないリクエスト URL に index.html を追加

ステップ7：動作確認

CloudFrontディストリビューションのデプロイが完了したら、管理画面に表示されているディストリビューションドメイン名（xxxxxxxx.cloudfront.netのような形式）にブラウザでアクセスしてみましょう。

• トップページが正しく表示されること
• ブログ記事など、サブディレクトリを持つページに直接アクセスしても正しく表示されること

上記が確認できれば、構築は成功です！ あとは、お持ちの独自ドメインをこのCloudFrontディストリビューションに向ける設定（Route 53などでレコードを設定）を行えば、独自ドメインでのサイト公開が完了します。

最後に

最後まで読んでいただきありがとうございました。 今回は、まずDocusaurusが持つ魅力と、そのサイトをAWSのCloudFrontとS3を使って公開する最適な手順をご紹介しました。

Docusaurusの手軽さと、AWSの堅牢で高速なインフラを組み合わせることで、非常に快適なサイト運用が実現できます。この記事が、あなたのサイト構築の参考になれば幸いです。