やったこと
- プロジェクトの新規ドキュメントはGitBookで作成しGitで管理
- 既存のドキュメント(Word、Excel、PDF、テキスト程度のメモ書きなど）はGitに登録
- GitbookのBuildはcommitが行われる度にJenkinsで自動的に実行
- Gitに登録されたドキュメントはFessサーバ内に日に1回pullする
- ドキュメント群をFessで毎日クローリングしインデックス作成
- 上記はすべてAWSで構築
全体構成
ざっくりとしたものですがこんな感じです。
GitBook構築
GitBookインストール
ざっくりと言うと、マークダウン形式でドキュメントを作成し、ビルドすることによって
htmlやPDFを作成し、公開したりプロジェクト内に展開できるツールです。
今回はAWSのEC2上に環境を作成しましたが、GitBook.com上でも行えますので用途に応じて変えたらよいと思います。
インストールに関しては、検索して出てきた先達の方々のを参考にして行いましたので、こちらでは割愛します。
プロジェクトメンバーに公開する
公開に用いたWebサーバはapacheの2.2系を用いました。
GitBookはプロジェクト内のチーム毎に作成しており、都度増減します。
その度にapacheのconfを書き換えるのは面倒なので、VertualDocumentRootを利用しました。
AWSのRoute53で社内用プライベートドメインを割り当て、そのサブドメイン毎にGitBookとJenkinsのジョブを作成します。
workspace以下をドキュメントルートとすることで定義の書き換えの必要性をなくしています。
<VirtualHost *:80>
ServerName [プライベートドメイン]
ServerAlias *.[プライベートドメイン]
VirtualDocumentRoot /var/lib/jenkins/workspace/%1/_book
<Directory "/var/lib/jenkins/workspace/%1/_book">
Options Indexes FollowSymLinks
AllowOverride All
</Directory>
</VirtualHost>
Jenkinsとの連携
GitBookとJenkins
Jenkinsの Gitlab Plugin を用いて、GitlabのCommitとビルドを連動するようにしました。
既存ドキュメントとJenkins
Jenkins内に最新のドキュメントを保持するのが目的です。
理由は後述するFessで利用するためです。
Fess構築
OSSの全文検索エンジンです。
公式にも書いてありますが。ElasticSearchを利用しており
WebAPIも対応しているため、WebベースでのGoogleライクな検索もできれば
APICallによるシステム内の検索部品としての役割も持つことができます。
現在はパッケージインストールに対応しているみたいなので、導入は比較的容易だと思います。
私の時（1年半ほど前）はなかった気がする…。
GitBookをクローリング
GitBookの公開URLに対してクローリングさせる設定を行います。
プロジェクト内で使っている名前などは[]書きで置き換えています。
既存ドキュメントのファイルクロール
FessにGitで管理しているドキュメントのインデックスを作成させます。
検索対象は、Jenkinsでリポジトリからpullしたドキュメントが格納されているフォルダです。
クロール対象とするパス項目で、検索で見つかるドキュメントをある程度制御しています。
全ファイル対象だと、不要なゴミファイルまで引っかかってしまったためです。
構築して思ったこと
- GitBookを使う場合はマークダウンに慣れていれば楽
- Fessでの検索はExcelなどの図形内テキストまで拾ってくれるので細かい検索ができる
- ドキュメントのアップデートが知りやすくなった
- OSSだけでもそれなりのものが構築できた
- Jenkinsおじさんは働き者