GitLabをインストールする際に陥った問題のまとめ

GitLabはGitHubのようなGitホスト環境を手元で構築できる、大変有益なツールです。

主なサポートプラットフォームはLinuxの各ディストリビューションですが、私はGitLab v5.3をFreeBSD 8.4 + ruby 1.9で利用しています。

やや環境設定で戸惑う事があったので、FreeBSD で動作させるコツと共に、ハマった点をまとめておきます。

FreeBSD へインストールする際の参考ドキュメント

FreeBSD へのインストールには、gitlab-freebsd/gitlabhqで公開されているインストールガイドが、大変参考になります。概ねこの手順に従えば、トラブルなくインストールが完了します。

なおgitlab-freebsd/gitlabhqではgitlabhq/gitlabhqのforkが公開されていますが、GitLabのコード自体へ特殊な変更が行われているわけではありません。オリジナルリポジトリへ、FreeBSDのportsと親和性の良い各種設定ファイルを同梱している、と捉えると分かりやすいと思います。

実際、forkされているコードは比較的古い版であるため、設定ファイルを参考に、オリジナルの最新版を動作させると良いでしょう。

FreeBSDではgitlab-shellへ注意

GitLabのv5系はgitlabhq/gitlab-shellへ依存しています。但し、gitlab-shell v1.6までのコードはFreeBSDでは動作しません。

gitlab-shellをFreeBSDで利用する場合にはf13afa2db3以降のコード利用する必要があります。

問題の本質はGNU sedとBSD sedの-iオプション引数取り扱いの差あり、変更差分はわずかです。

FreeBSD向けGitLab起動スクリプト

FreeBSD向けGitLab起動スクリプトとしては、Eyes JAPAN Blogで公開されているスクリプトが綺麗にまとまっており、利用させていただいています。

但し、ここで公開されているスクリプトの最新版にはバグが有り、重要な外部プログラムであるsidekiqが動作しません。

修正した版をgistで公開していますので、こちらの利用をお薦めします。本質は変数の初期設定ミス修正です。

repos_path へは symbolic link を含んではならない

gitlab/config/gitlab.yml ならびに gitlab-shell/config.yml へはrepositoryを格納するディレクトリを設定するrepos_pathがあります。コメントへ書かれている通り、この値はsymbolic linkを含んではいけません。

ここで注意すべきは、FreeBSDを標準設定でインストールした場合、/homeディレクトリが、usr/homeへのsymbolic linkとしてインストールされることです。

結果、GitLab標準設定に基づき、repos_pathとして/home/git/repositories/を指定すると、結果的にsymbolic linkを含んでしまうことになります。

もしこのディレクトリを使いたい場合には、明示的に/usr/home/git/repositoriesと設定するか、/homeの位置を再調整する必要があります。

sidekiq が動作していることを確認する

FreeBSD へ限った話ではありませんが、GitLabではsidekiqプロセスが正しく動作していることが非常に重要です。

sidekiqプロセスが動作していない場合、表面上は正常に動作しているように見えるものの、実際には正常動作しない、という、分かりにくい状況へ陥ります。

例えば、Web画面ではssh鍵の登録が正常終了したように見えたにも関わらず、実際には、authorized_keysへ鍵が登録されていない、といった状況や、プロジェクトの作成指示が正常動作したように見えたにも関わらず、repos_pathで指定したディレクトリ内へはリポジトリが作られていない、という状況になった場合、sidekiqプロセスが、正しく動作していることを確認すると良いでしょう。

例えばsidekiqが正常動作している場合、psでは次のように見えます。

# ps ax | grep sidekiq
41032   0  I      0:22.50 ruby19: sidekiq 2.11.1 gitlab [0 of 25 busy] (ruby19

なおsidekiqプロセスは、GitLabの起動スクリプト内で起動されることが一般的です。うまく動作しない場合にはスクリプトを確認すると良いでしょう。

.ssh/authorized_keys 内の鍵へ注意する

これもFreeBSD へ限った話ではありませんが、GitLabを動作させているユーザの .ssh/authorized_keys ファイルは、リポジトリアクセス権管理に使われる重要なファイルです。

何らかの不具合により、このファイル内へ同一の鍵が複数個登録されてしまった場合、GitLabが正常に動作できなくなる可能性があります。

GitLab 管理下にある repository へ push を行った際、

fatal: Could not read from remote repository.
Please make sure you have the correct access rights
and the repository exists.

といったメッセージが表示された場合、.ssh/authorized_keys が正しいかどうかを確認すると良いでしょう。

なお、鍵が正しくインストールされている場合、

% ssh -t gitlab@GitLabServerName.example.com

とのコマンドに対し、

Welcome to GitLab, <YOUR USER NAME>

との応答が返ります(<YOUR USER NAME>はGitLabで登録したユーザ名です)。この応答が返らない場合、鍵設定に問題のある可能性があります。

GitLabは大変便利なツールです。ツールの規模がやや大きいため、トラブルシュートでやや混乱しがちですが、設定ファイル自体はシンプルなため、問題を適宜切り分ければ、対処は難しくないと思います。

Tempus - 昨今明日

2013/07/20