マークダウンをブラウザで見れるMkDocsをGitBucketと連携して自動更新する

こんにちは、久々に書きます、まだ新卒の久保田です。

今日は、最近とても便利で気に入っている仕組みを作ったので、そのことについてです。

さて、エンジニアってとても覚えること多いですよね。

一生勉強とはよく言ったものです。

みなさんはどのようにしてこの膨大な知識をためているでしょうか？

ノートですか？

それともQiitaなどのブログ？

それともパソコンの中にテキストファイルを書いているでしょうか？

こだわりの強い人はmarkdownかもしれませんね。

ものすごい頭いい人はそんなものはいらねぇっていうかもしれませんね。

僕は開発環境にdocsというディレクトリを作り、テキストファイルをためていっているのですが、

これがまた見づらいのです。僕もマークダウンで書きたい。でもブログとかは続かないからやりたくない。(そもそもメモ程度のことをブログにしたくない)

そんなとき、先輩に教えていただいたのが、「MkDocs」というサービス。

マークダウンで書いたファイルをブラウザで見れるようにしてくれるものです。

しかも検索機能のおまけつき。

これはいい！と思ったのですが、結局ローカルで運用するのはいつかやらなくなりそうだなと思い、
GitBucketと組み合わせて、こんな風にしようと思いました。

(GitBucketは、Githubのクローンで、個人でGithubがもてるみたいな感じです。)

GitBucketのwebhookを利用し、pushされたら、MkDocsサーバーがpullして自動更新するという仕組みです。

これならローカルで書いたメモをgit で pushするだけでページが自動更新がされ、便利そう！

公開したくなかったらapacheにベーシック認証つければいいですし。

というわけで作っていきましょう。

1 - MkDocs用のサーバーとGitBucket用のサーバーを用意

僕はAWSのEC2でやりましたが、なんでもいいです。1つのサーバーでもいいですし、適宜読み替えてください。

まず、MkDocs用のサーバーをセットアップします。

sudo yum install python-setuptools
sudo easy_install pip
pip install mkdocs

#mkdocs用のプロジェクトを作成
mkdocs new mkdocs

#設定ファイルを編集(mkdocs/mkdocs.yml)
docs_dir: /path/to/mkdocs/docs #追記する

# 動作確認
cd mkdocs
mkdocs serve -a 0.0.0.0:8000

ip:8000 にアクセス

こんなのがでてきたらOK!

ここで、デフォルトのdocsを消しておきます。(後にgitリポジトリをcloneしてそれを使うため)

rm -rf mkdocs/docs

gitをインストールします。

sudo yum -y install git

次に、GitBucket用のサーバーのセットアップです。

sudo yum install -y java-1.8.0-openjdk java-1.8.0-openjdk-devel java-1.8.0-openjdk-headless
sudo yum install -y tomcat --enablerepo=epel
sudo wget -P /usr/share/tomcat/webapps/ https://github.com/takezoe/gitbucket/releases/download/3.0/gitbucket.war

# 動作確認
sudo service tomcat start

ip:8080/gitbucket にアクセス

こんなのがでてきたらOK!

(初期パスワードはroot: rootです)

2 - ローカルにメモを書く用のgitリポジトリを作成

ローカルにメモをためて行く用のリポジトリを作っておきます。

mkdir docs
cd docs
git init
touch index.md
# index.mdを作らないとmkdocsのトップページがなくなります

3 - GitBucketにリポジトリを作成

この辺は普通のgitと同じです。

右上に New repositoryボタンがあります。

4 - first commit

作ったリポジトリにfirst commitしておきます

git add .
git commit -m 'first commit'
git remote add [url]
git push -u origin master

5 - ここからが面白いところです。作ったGitBucketのリポジトリにweb hookを登録しておきます。

git にはフックという機能があり、こちらを使うと特定のアクションがあった後になんらかのイベントを起こせます。

(how to 上司にほめられるための git　~フックスクリプト編~　http://blog.engineer.adways.net/archives/git/howto/3.html#more)

GitBucketに先ほど作ったリポジトリの、右のほうにあるSettingをクリックし、左メニューのService Hooksをクリックします。

すると以下の画面が出てきます。

ここに、これから作るエンドポイントを登録しておきます。

(ここで指定するアドレスにアクセスすると、MkDocsがGitBucketのリポジトリをpullするスクリプトが動くようにこれからなります。)

6 - MkDocsに作ったリポジトリをclone

先ほどGitBucket用に作ったリポジトリをMkDocs用のサーバーにcloneしておきます。

自動更新を実現するため、一度git pullして、MkDocsの機能を使ってmarkdownからhtmlに変換する必要があるためです。

git clone [url]

そして、cloneしたリポジトリに移動して、パスワードを設定しておきます。これをしておくと、git pullするときに認証を自動で行います。

# cloneしたリポジトリで、./git/configを編集

originのurlのホストの前に以下の形式でユーザー名とパスワードを追記します

url = http://ユーザー名:パスワード@ホスト:8080/gitbucket...

7 - エンドポイントの作成

MkDocsのサーバーに、リクエストがきたらリポジトリからcloneし、

MkDocsのbuildの機能を使ってmarkdownから生成したhtmlを配置するruby プログラムを作ります。

一番の肝となるところですね。

僕はRubyのwebrickを使って作りました。

#webrick.rb

require 'webrick'

# デーモンで実行
Process.daemon

srv = WEBrick::HTTPServer.new({
Port: 'GitBukcetのWebHookに登録したポート番号'
})

srv.mount_proc '/' do
`git -C /path/to/mkdocs/docs pull`
`sudo /usr/local/bin/mkdocs build -f /home/ec2-user/mkdocs/mkdocs.yml -d /var/www/html/`
end

srv.start