開発用のドキュメントを整備する第一歩

[ta1kt0me]

開発環境構築が何かと大変らしいので、ドキュメントを書いてみました。

やったこと

• homebrewのインストール
• rubyのインストール
• kajaeru起動までの手順

その他

• 手元に色々入ってしまっているので手順の確認ができない 😢 初めての人が参考にしてみて必要があれば追記とかでどうでしょうか。

[yucao24hours]

ありがとうございます！ 👍 👍 👍
#119 でもいろいろ書きなおそうとしていたので、合わせてやってしまうといいのかな。

[shokola]

あの、私だけが分からないだけかもしれないのでここにコメントするべき(idobataのが良かった？)かわからないのですが、
Kajaeruって database.yaml ないですよね？どうやって bin/rails db:setup したらいいのかわからないのです？？

[ManabuSeki]

@shokola 横から失礼します
wikiの開発環境構築で

cp config/database.yml.sample config/database.yml

でサンプルからコピーしてます

[shokola]

wikiにあったのかー！

config/database.yml を自分の環境にあわせて適宜修正する そういう運用なんですね。

無事動きました。gitHubのサインイン404だけど。。。

[ManabuSeki]

@shokola
環境構築wikiから消えてた
のでこちらに残しておきます

GitHub で行う準備

Kajaeruのログイン機能はGithub APIのOauthを利用するため、こちらより、Developer applicationsに登録し、Kajaeruのための Client ID と Client Secret を取得してください。

設定内容サンプル

localhost:3000を環境に応じて変更してください。

• Application name（任意）
  • kajaeru
• Homepage URL
  • http://localhost:3000
• Description
  • ruby kaja投票アプリ
• Authorization callback URL
  • http://localhost:3000/auth/github/callback

[ManabuSeki]

書いておいてあれなんですけど、、、自信ないので誰かわかるかたコメントください

[ManabuSeki]

#128 でマージされてるのでAuth登録不要になった

[5t111111]

@shokola @ManabuSeki

無事動きました。gitHubのサインイン404だけど。。。

流れでこの issue に書きます。

development で動かしたいとき

#141 (comment) で書いてくれている通り、#128 の取り込みにより、今は開発時に development 環境で動かす場合には GitHub の OAuth 認証をしなくてもよいようになっているので、GitHub で Developer applications の登録も不要です。

もし development で動かしている (普通に手順の通りに bin/rails server で起動している) ときに GitHub と接続していてうまくいかない場合はローカルのプロジェクトの状態が古いと思うので git pull で更新を取り込んでください。

production で動かしたいとき

Kajaeru は環境変数の扱いを楽にして、デプロイ先の Heroku アプリケーションの構成を簡単にするために figaro という gem を使っています。

この gem のおかげで、config/application.yml というファイルに環境変数を設定しておけば自動的に読み込んでくれたりします。

ただ、現在は上記したように development では OAuth 認証をしないようになったので開発環境構築手順からも config/application.yml を用意する手順がなくなって、さらに、 config/application.yml を用意したとしても production 環境で起動したときはそこで設定した環境変数が読み込まれない (結果、GitHub の developer application 連携をしにいくときに Client ID とかが空で 404 になっちゃう) という状況になります (これはやってみたらそうなっただけで、詳しくないので正しい動きかわからない) 。

したがって、実証ベースの話だと、production で動かしたいときには自分で以下の環境変数を設定する必要があります。例えば一番基本的な、rails を起動するターミナルで設定する方法だと、GitHub で developer application を登録したあと、↓のようにその情報を環境変数として設定するやりかたになります。

$ export GITHUB_CLIENT_ID=xxxxxxxxxxxxxxxx
$ export GITHUB_CLIENT_SECRET=xxxxxxxxxxxxxxx
$ bin/rails server -e production

とりあえずこれで動かすことはできます。

環境変数は方法はいろいろあって (自分は環境変数周りは何やるときも direnv で統一してる) 、figaro をそのまま使う方法も調べてないだけであるかもしれませんが、前も言ったように production で動かすには他にもいろいろ環境変数を設定したり特有の手順が必要になるので、開発環境の構築手順とは別途用意したほうが良さげですね。

[5t111111]

ちょっとレビューしてみようとして、rbenv とか ruby-build は Homebrew 経由でインストールするのがいいのか、それとも git clone がいいのか、でも結局 Ruby のビルドに依存ライブラリいるから Homebrew 要るかな、いやそうすると Xcode の話から要るのかな、ていうかそもそも「普通の OSS」的な README にするんなら README には実行環境の構築手順があるのも変だよね、てか英語で書く意味あるだろうか？とか考えてたら完全に心が折れたので、

もう Cloud9 でいいじゃん

というところに行き着きました。行き着いてだいぶ勝手ですがそのための wiki ページも作りました。

https://github.com/yochiyochirb/kajaeru/wiki/using-cloud9

思うに、ドキュメント化したとしても、この実行環境構築の話ってたぶんずっと付いて回る気がするのと、実際にこないだ Kajaeru のペアプロのときに Cloud9 を使っていた方が2人いて快適そうだったので。実際ログインさえできれば (あと yochiyochirb の organization の権限さえあればかな) 瞬殺で十分な環境が構築できるので、やり方として用意しておくことでマイナスになることは何もないかな、と。
(※画面も貼り付けたので UI とかすぐ変わったりはしそうですけど)

どんな感じでしょう。

[shokola]

あーもう環境構築の手間(ハマり)やドキュメント整備で悩むのはもうやめようってことか。
IDEの良さを感じるのも良いかと思います(私個人の意見)

[5t111111]

もちろんドキュメント整備とかを完全にやめてしまうんじゃなくて、ハマりにくい選択肢も用意しつつ README でフォローする範囲は絞りたいって希望ですね。今のところ wiki に逃がすのが最適かと思ってる。

もちろん Kajaeru の特有の導入手順だとか、上で書いた production で動作させたいときの説明だとかは README にあって良い、というかあった方がよいと思います。

ただ、あくまで Kajaeru ミートアップの時間に実行環境の構築でせっかくの時間を開発に使えない、というのをどうにかしたいってのがこの issue が解決すべきところだと思っているので、個人的には↓みたいなのを想定してます。

1. ミートアップ申し込みの段階で、(前やってたみたいに) 前提条件を提示
   • Ruby 2.3.0 がインストールされていること
   • ruby -v の結果が 2.3.0 であること
2. 前提条件を満たしていない場合の対策を同時に提示
   • OS X で Homebrew を利用した Ruby 2.3.0 の実行環境構築手順 (wiki?) を案内 ( @ta1kt0me がここで書いてくれてるやつ)
   • 上記が難しい、うまくいかない人向けとして Cloud9 でログインまでやっておいてもらえるように手順 (wiki?) を案内
3. 基本、ここまでのいずれかをやってもらえれば、あとは各自の環境にしたがって README の手順に沿って Kajaeru を導入すれば開発をスタートできるはず (希望的観測)

[ta1kt0me]

コメントありがとうございます。このPRですが次の方針で修正しようと思います。過不足あればアドバイスいただけると。

READMEに記載すること

1. rubyが入っていることを前提にしてkajaeruを起動するまでの手順を記載
   • 具体的にはwikiのこのへんをREADMEに移行する
2. テストの実行方法
   • cucumberでテストを実行する方法
   • minitestかrspecかは RSpec 関連のファイルや設定を消す [closes #121] #134 の流れを見守りつつこのPRでは対応しない
3. Productionでの起動方法
   • 開発用のドキュメントを整備する第一歩 #141 (comment) のherokuの利用を想定したproduction で動かしたいときの手順を追加
     • GitHubのtoken発行手順も追加(refs: [WIP] README に必要な情報を集める #119 )
4. 開発環境構築のためのwikiのURL
   • Railsアプリケーションを動かすためのrubyなどのツールの導入
     • wikiに用意する
   • @5t111111 の用意したhttps://github.com/yochiyochirb/kajaeru/wiki/using-cloud9

[yucao24hours]

みなさん、いろいろ考えていただいてありがとうございます。

このPRですが次の方針で修正しようと思います。

@ta1kt0me LGTM. このとおり修正していただけると助かります 🙇

今後はミートアップ参加者募集の際にはあらかじめ Kajaeru の開発環境を作っておいてもらうことをお願いするようにしようと思います。それで、もしもそれができずに当日参加なさった方がいらしたら、Cloud9 を使っていただくようなフローにしようと思います。