Tech Sketch Bucket of Technical Chips by TIS Inc.

Sphinxで作成したドキュメントをAmazon S3でWebに公開する

Pocket

この記事はeXcale Developer's Blogから移転されたものです。

 こんにちは、eXcale開発チームの平井です。

 Sphinxは、美しいドキュメントを簡単に生成することができるツールです。reStructuredTextというマークアップ言語で文書を作成すれば、HTMLやPDF、ePubといった複数の形式に出力する事ができます。

 今回は、Amazon S3のWebホスティング機能とRubyのライブラリ(s3sync)を使用して、Sphinxで作成したHTMLドキュメントを、かんたんにWeb公開する方法をご紹介します。

 冒頭で書いたように、Sphinxは、ドキュメント生成ツールで、reStructuredTextというマークアップ言語で書いた文書をHTMLに変換することができます。通常であれば、HTMLドキュメントをWeb上に公開するには、Webサーバ(Apache HTTP ServerNginx)などのセットアップ作業やサーバの運用管理といった面倒な作業をしなければなりません。しかし、Amazon S3のWebホスティング機能を使用すると、そのような手間をかけることなく、かんたんにドキュメントをWebに公開することができます。Webホスティング機能は、静的なWebサイトを公開するための機能です。この機能を使うことで、Cloud Design Pattern(CDP)で紹介されているDirect Hostingパターンを実現することができます。実際に、私達が開発・提供しているeXcaleのドキュメントサイトもSphinxとS3のWebホスティング機能を用いて公開しています。

 今回ご紹介する内容の題目は以下となります。

  • S3バケットの設定(Webホスティング機能を有効にする)
  • S3バケットのポリシー設定(アップロードするファイルを誰でも見れるようにする)
  • 公開するサンプルドキュメントをSphinxで作成
  • s3syncでのS3へのアップロード
  • 独自ドメインでの公開について

S3バケットの設定(Webホスティング機能を有効にする)

 Amazon S3で、静的Webサイトのホスティングをするには、通常のバケット作成の他に設定の変更をする必要があります。設定は、該当バケットのプロパティ画面で行います。また、そのWebサイトを独自ドメインで公開する場合はバケット名に注意が必要です。バケット名はその公開するWebサイトのFQDNと一致させる必要があります。例えば、http://doc.excale.net/で公開する場合、そのバケット名はdoc.excale.netとしなければなりません。

 バケット作成後、下図の①で示す虫眼鏡アイコンをクリックすると、そのバケットのプロパティを開くことができます。Webホスティング機能の設定をするには、下図の②をクリックします。

 "Static Website Hosting"をクリックして表示される内容は以下となります。

 デフォルトでは、Webホスティング機能が無効("Do not enable website hosting")となっていますので、これを有効("Enable website hosting")にします(図の①をクリック)。有効にする場合、インデックスとなるファイルと、アクセスしようとしたファイルが存在しなかった場合などのエラーだった場合のファイルを指定する事ができます。今回は、インデックスとなるファイルをindex.htmlと設定します(図の②)。また、図の矢印で示したEndpoint(<bucket-name>.s3-website-<AWS-region>.amazonaws.com)にアクセスすることで、Webサイトを表示することができます。


S3バケットのポリシー設定(アップロードするファイルを誰でも見れるようにする)

 S3バケットの設定で、Webホスティング機能を有効にしただけでは、権限設定が足りずアップロードしたファイルを表示することができません。そのため、次に、バケットのポリシー設定をします。

 ポリシー設定は、バケットのプロパティの"Permissions"から設定します。"Permissions"をクリックすると下の図のような画面になりますので、図の矢印で示した"Add bucket policy"をクリックします。

 "Add bucket policy"をクリックすると、次のようなダイアログが表示されます。ここで、ポリシーを設定します。

 設定するポリシーは、公式ドキュメントで紹介されているものです。全てのユーザに対して、読み込み権限を付与します。8行目のexamplebucketは、今回公開しようとしているバケット名に変更して下さい。

 上記内容を入力して、"Save"ボタンをクリックすると、バケットのプロパティ画面に戻ります。下の図の赤丸で示した"Permissions"設定の"Save"ボタンを押せば設定完了です。

 この状態で、Webホスティング機能の設定で確認したURLにアクセスすると、"404 Not Found"となります。"404 Not Found"ではなく、"403 Forbidden"となった場合、ポリシーの設定が間違っていると思われるので、ポリシーの設定を確認してみてください。


公開するサンプルドキュメントをSphinxで作成

 公開する基盤の準備は出来たので、公開するコンテンツを準備します。今回は、sphinx-quickstartで作成されるドキュメントのひな形を公開します。

 Sphinxは、Python製のツールで、easy_installでインストールすることができます。2014年4月25日時点の最新バージョンは1.2.2となります。

 Sphinxのインストールやマークアップ言語については、以前にこのブログで取り上げていますので(Sphinxでドキュメントを作る (インストール編) Sphinxでドキュメントを作る (マークアップ編) )、そちらも参考にしてみてください。

 Sphinxをインストールすると、sphinx-quickstartというひな形のドキュメントを作成するコマンドが使えるようになります。sphinx-quickstartを実行すると、作成するドキュメントの設定について対話的に設定していくことになります。今回は、設定は変えず、デフォルトのままとしています。

 ひな形が作成できたら、そのHTMLドキュメントを作成します。HTMLドキュメントはmake htmlで作成できます。HTMLは"_build/html"に作成されます。


s3syncでのS3へのアップロード

 SphinxでHTMLドキュメントが作成できたので、これを公開するために、S3にアップロードします。S3へのアップロードはAWSのManagement Consoleからもできますが、今回のように特定ディレクトリ以下全部をアップロード、また、変更毎にアップロードする、となると非常に手間がかかってしまいます。このような場合、Rubyのライブラリであるs3syncを使うと、手間をかけること無くかんたんにアップロードできます。gemでインストールすることができます。

 s3syncは、その名前の通り、ローカルのファイルとS3を同期させること(アップロード)、もしくは、その逆でS3のファイルをローカルと同期させること(ダウンロード)ができます。また、同期なのでローカルで削除したものは、S3側も削除されます。そのため、S3から不要なファイルを削除する、といった事を気にする必要はありません。

 実行は次のようになります。実行前に環境変数にAWS_ACCESS_KEY_IDとAWS_SECRET_ACCESS_KEYを設定する必要があります。

 s3sync sync実行時に、オプションとして-d(dry-runとなる)や-v(詳細表示となる)をつけることで、どのようなファイル操作が行われるのかを確認することができます。

 アップロード後、バケット設定時に確認したURLを表示して、次のような画面が表示されればOKです。


独自ドメインでの公開について

 ここまでの設定で、<bucket-name>.s3-website-<AWS-region>.amazonaws.com にアクセスすればドキュメントを表示できるようになります。このドキュメントを自分が所有する独自ドメインで公開する場合はさらにDNS設定が必要になります。例えば、doc.example.comで公開する場合は、以下の様なCNAMEレコードを設定します。

  • Name : doc.example.com
  • Value : doc.example.com.s3-website-<AWS-region>.amazonaws.com

 また、バケット設定のところでも書きましたが、独自ドメインで公開する場合はバケット名に注意が必要です。バケット名はその公開するWebサイトのFQDNと一致させる必要があり、例えば、doc.example.comで公開する場合、そのバケット名はdoc.example.comとしなければなりません。

最後に

いかがでしょうか、今回紹介した方法を使えば、ドキュメント作成/修正からWebへの公開/反映が非常にかんたんにできるようになりますので、ドキュメントをWebで公開する場合に参考にしてみてください。

エンジニア採用中!私たちと一緒に働いてみませんか?