くりにっき

ドリコムのプリキュアの人です

GemoireというYARDホスティングアプリを作りました

上記エントリのスライドでもちらっと書きましたが、YARDドキュメントホスティングアプリを作りました。

名前の読み方と由来

Gem + Grimoire (グリモワール = 魔導書) = Gemoire (ジェモワール)

gemの魔導書(取扱説明書)を多数集めた本棚をイメージしています

背景

仕事では各種gemを作ったりメンテすることが多いのですが、ドキュメントを手軽に公開できる環境がないのが難点でした。

今自分がメンテしてるgemだとJenkinsのpost build taskでspec実行後にyardを生成して外部から見れるところにコピーしています。

f:id:sue445:20140927234246p:plain

ただ、

  • アプリごとに野良Jenkinsが乱立してるのでドキュメント化を全社に展開しづらい *1
  • 公開用のドキュメントを作るだけでJenkinsを使うのも大げさ
  • ドキュメント生成のためだけにdependencyにyardを追加するのも違和感がある

のような事情で RubyDoc.info のクローンを目指して作りました。

全体像

f:id:sue445:20140927233715p:plain

  1. ホスティングリポジトリにpush
  2. pushを受けてホスティングリポジトリがGemoireにwebhookに通知
  3. Gemoireがホスティングリポジトリからソースをclone
  4. yardドキュメントを生成してブラウザから見える場所に配置

図にもありますがGithub, bitbucket, gitlabに対応しています *2

特徴

  • ホスティングサイトに依存しているのはwebhookの部分だけなので、git clone できるリモートURL(http, https, git, ssh)であれば何でも使えます

必要なもの

Herokuで使う場合に注意すること

  • デプロイする度にドキュメントが消えます
    • git cloneしたリポジトリや生成したドキュメントをアプリ配下に置いているため
  • リモートURLにsshが使えません
  • Dynoが1つだとSidekiqによる非同期処理ができません

社内に立てた時に変えたこと

ドキュメントとサテライトリポジトリ(cloneしたリポジトリの置き場所)は別ボリュームにした

config/global/gemoire.yml はこんな感じ

default:
  doc_root_dir:       public/doc
  satellite_root_dir: tmp/satellite
  time_zone:          Tokyo
  doc_path:           /doc
  # doc_path:         http://doc.example.com/

development:

test:

production:
  doc_root_dir:       /data/doc
  satellite_root_dir: /data/satellite
  time_zone:          Tokyo
  doc_path:           /doc

public/doc は/data/doc へのシンボリックリンクです

リポジトリのサイズがでかくなることを想定してrootパーティションではなく念の為別ボリュームの dataパーティションを作ってますが、普通にsharedでよかったかもしれない

capistrano追加

padrino用のcap taskがなかったので lib/capistrano/tasks/padrino.cap にこんなのを作った

namespace :deploy do
  set :db_environmental_variables, -> {
    {
      rack_env: fetch(:rack_env),
    }
  }

  namespace :ar do
    desc "ar:migrate"
    task :migrate do
      on roles(:app) do
        within release_path do
          with fetch(:db_environmental_variables) do
            execute :rake, 'ar:migrate'
          end
        end
      end
    end
  end
end

その他細かいところ

その他

  • 今回初めてPadrinoでアプリを作りきりましたが、起動が早いのでHerokuとの相性がいいですね
  • capistrano便利なんだけど初期セットアップめんどい

*1:野良Jenkinsに関しては賛否両論あると思いますが、作るアプリによって必要なビルド環境は異なるしJenkinsの運用ノウハウを知ってる人は多いにこしたことがないので弊社だとこのスタイルがあってると思ってます

*2:他のホスティングリポジトリに対応してほしければPullRequestカモン