2015-10-29

Sphinx を Cloud Foundry で動かす

「Cloud Foundry 百日行」第89日目，今日は3回シリーズ「静的サイト・ジェネレーター」の最終回，Python ベースのドキュメンテーション生成ツール Sphinx です。前2回の Jekyll, Hugo がブログ寄りであったのに対し，Sphinx はマニュアル等のドキュメンテーションを意識したツールということで，若干毛色は異なる印象です。

基本情報

手順の概要は以下の通りです。

  • 1) 静的サイトのサンプルの取得
  • 2) Cloud Foundry 向けのカスタマイズ
  • 3) Cloud Foundry へのデプロイ
  • 4) 動作確認
  • 5) まとめ

1. 静的サイトのサンプルの取得

前々回, 前回 同様，Cloud Foundry にデプロイするサイトのサンプルとして，百日行シリーズの最初の2つの記事を使います。元のフォーマットは Markdown で，それを reStructuredText に手動で書き直しましたが，内容的には同等です。

サンプルは GitHub に置いてあるので，試してみられる方は以下の手順で clone してください。

$ git clone https://github.com/nota-ja/cf-sphinx-example.git
..
$ cd cf-sphinx-example/

2. Cloud Foundry 向けのカスタマイズ

今回はカスタム buildpack を使わず，Cloud Foundry 標準の buildpack である python-buildpack だけを使ってサイト作成 / serve を行います。作業としては以下の3つのファイルを追加するだけです。

  1. pip を使って sphinx をインストールするための requirements.txt を用意する
  2. 起動時にサイトのビルドと Web サーバーの起動を行うための Procfile を用意する
  3. (optional) Cloud Foundry 環境に余分なファイルをアップロードしないために，.cfignore ファイルを用意する

2.1. requirements.txt

以下の内容の requirements.txt をリポジトリーのトップ・ディレクトリーに置きます。

$ cat requirements.txt

sphinx

2.2. Procfile

make html でサイトをビルドしたあと，build ディレクトリーに移動して Python の Web サーバーを起動する Procfile を作成し，リポジトリーのトップ・ディレクトリーに置きます。

$ cat Procfile

web: make html && cd build/html && python -m SimpleHTTPServer $PORT

2.3. .cfignore

不要なファイルが Cloud Foundry にアップロードされるのを避けるため，cfignore を追加します。Sphinx のデフォルトのビルド・ディレクトリーは build なので，build を含めておきます。

$ cat .cfignore

*~
.*~
/build

3. Cloud Foundry へのデプロイ

以上で準備が整ったので，Cloud Foundry にデプロイします。

$ cf push sphinx-example

Creating app sphinx-example in org nota-ja / space prod as nota-ja...
OK
..
requested state: started
instances: 1/1
usage: 256M x 1 instances
urls: sphinx-example.10.244.0.34.xip.io
last uploaded: Wed Oct 28 11:16:54 UTC 2015
stack: cflinuxfs2

     state     since                    cpu    memory          disk      details
#0   running   2015-10-28 08:17:36 PM   0.0%   63.3M of 256M   0 of 1G

起動しました。これもメモリはデフォルトの 256MB のままにしていますが，もう少し減らしても大丈夫そうです。

4. 動作確認

ブラウザーでアクセスしてみた時のトップ画面はこんな感じです：

各ページを表示させてみます：

画像の表示も確認しました：

以上で動作確認は終わりです。

5. まとめ

「静的サイト・ジェネレーター」シリーズ第3弾，最終回は Sphinx を試してみました。本記事はカスタマイズを極力減らす方針での試行だったのですが，いかがだったでしょうか？

今回「静的サイト・ジェネレーター」という同種のアプリのくくりで，さまざまなデプロイのパターンを試してみましたが，まとめるとおおよそ以下のようになると思います。

Generator Buildpack(s) Web server site generation
Jekyll custom, multi custom(*1) on staging
Hugo custom built-in(*2) on startup
Sphinx standard built-in on startup

(*1) メインの buildpack に含まれない Web サーバーを使用
(*2) メインの buildpack 内で調達できる Web サーバーを使用

各サイト・ジェネレーターは今回のシリーズで試したパターンでしかデプロイできないわけではなく，上記のさまざまな組み合わせでデプロイできると思います。どのパターンが良いかは，使っているツールや，サイトの更新頻度，負荷の状況等によって変わってくると思いますので，ご自分のサイトに適したパターンを試してみてください。

今回使用したソフトウェア