docker使うと、デプロイ方法の細かいところをインフラ担当者と話す手間がなくなるからお互い嬉しいですね。
今回は、なるべく手をかけずにWEBのマニュアル smpdoc.shanon.co.jp を構築した話を書きます。
今までは、google docsに書いたマニュアルをPDF化してサポート担当者に連絡してサポートサイトに公開していました。この作業が非生産的で改善したいけど、社内でプロジェクト化するには、優先順位の低い課題でした。
いかに手をかけずにWEB化するか。出来る限りOSSを使って維持管理を楽にするというポリシーで設計しました。
私達が提供するサービスのマニュアルは、表形式で表現することが多いため、今回はmarkdownよりも表形式の表現がいろいろ可能なasciidocで構築することにしました。
また、全文検索できないとダメと企画おじさんから言われたので、htmlをAWS S3に配置すして公開する形式ではなく、gitbookを使いました。
gitbookの構成
gitbookの構成は以下の通りです。
デプロイ後asciidocで作成したコンテンツを変更することはないので、コンテンツ全てを含めたgitbookのコンテナを作成しました。
- github上にasciidocのファイルおよびdocker buildのソースを作成
- github上の構成はこんなイメージ
├── README.adoc [表紙]
├── SUMMARY.adoc [メニュー]
├── .gitignore [localでのdebug時、docker build時にできる一時ファイルを設定]
├── .bookignore [gitbookで公開しないファイル(docker関連、開発者へのasciidocの記述ルールなど)を設定]
├── docker
│ ├── base [centosのdocker file]
│ ├── gitbook [gitbookのdocker file]
│ └── webfront [nginxのdocker file]
├── documents [ここにasciidocのファイルを作成していく]
├── node_modules
│ ├── gitbook-plugin-theme-shanon [本サイト用のgitbookのデザイン]
│ └── gitbook-plugin-toggle-chapters
└── usage [開発者へのasciidocの記述ルール]
gitbook構築時のポイントは２つあります。
- gitbookのデザイン変更は、pluginを作成する。（私は corezoid社のpluginを参考にしました。）
- 本番環境でgitbook を起動するときは、引数に「--no-watch」を入れる。（そうしないと、LiveReloadingが本番でも実行される。大概LiveReloadingのportに接続できずにブラウザのconsoleでエラーが出る。）
ビルド・デプロイ
1. 「上記作成したgitbook」と「nginx」のイメージをdocker-composeで連携してJenkinsビルド環境でimegeを作成後、社内のdocker registryにpushします。
（実際は、githubのpull requestをマージしたタイミングでJenkinsでビルドしています）
2. 本番公開したいときに、デプロイ用のJenkinsでdocker registoryからpullしてコンテナを起動してデプロイします。
感想
- Jenkinsのボタンを押すだけで公開できるので、楽になった。
- WEB化したのでGoogle Analyticsを入れてアクセス数を定量的に計測できる。（公開して半年経つが、何もしていない割にはアクセス数が増えている）
- SUMMARY.adoc のメニューの数によって、立ち上げに時間がかかる。（現時点でファイルが約900、メニューが約250あるが、gitbookコマンドでWEBサイトを立ち上げるまでが4分かかる。）
- asciidocでまとまっているので、PDFも作成できるように来年やる予定。
最後に...
最も大変だったことは、google docsのコンテンツをasciidocに変換する作業でした。
ここは、周りのメンバーに協力していただき人海戦術で対応しました。ありがとうございました。
