いきさつ: 研究室Wikiのオンプレミス運用やめたい
私の研究室ではオンプレミス環境で Gollum Wiki を動かしていたのですが、去年の春にサーバー管理者が不在になってしまいました。サーバー管理者がいないのに（しかも非情報系の研究室が）サーバー運用を続けるのは技術コストもリスクも高いので、クラウドに Wiki を移そうということになりました。
必要条件はこんな感じです。
- クラウド型
- Gollum Wiki で使っていた大量の
.mdファイルをインポートできる - プライベート Wiki
- やる気がマシマシになるナウい UI
クラウド型 Wiki の候補
クラウドで使える Wiki サービスをざっと探したところ、大体こんな感じになりました。
GROWI.cloud
オンプレミス Wiki サービス、Crowiのアップデート版？であるGrowiがクラウド版になったものです。
メリット
- UI がかっこよい
- hackmd を取り入れた多人数同時編集
- OAuth 認証できる
- 操作が直観的
デメリット
-
.mdファイルのインポートができない - まともに使おうとすると有料
もしお金があって、クラウド型の Wiki を新たに始めたいということならば最適解かもしれません。今回は.mdファイルをインポートできないことが致命的な欠点となり、導入を見送りました。
Dropbox Paper
天下の Dropbox のドキュメントサービスです。イメージ的にはマークダウンが使えるシンプルな Google Docs みたいな感じです。
メリット
- 誰でも使える
- ハードルが低い
- WYSIWYG
-
.mdのインポートも API を叩けばできる
デメリット
- マークダウン書式が一部しか対応してない
- リンク貼りやページの相互参照が独特なので結構困る
- 編集モードと閲覧モードの切り替えができない
Dropbox ということで技術コストもかなり低く、非情報系の研究室にはとても良いです。が、API を叩くのが面倒マークダウン書式が一部しか対応しておらず手動で記事を書き換える必要があるのが辛かったので、こちらも導入を見送りました。
GitHub Wiki
(画像は上記リンクのスクショ)
GitHub にある Wiki 機能を使う方法です。個人のレポジトリでも使えますが、研究室などの組織で使う場合は GitHub Organization のアップグレード版 Teams を作成することになります（後述）。
メリット
- みんな大好き GitHub
- UI もシンプル
-
.mdのインポートが一瞬
デメリット
- 画像の扱いが面倒
- ファイルが 100MB までしか扱えない
.mdのインポートができる！素晴らしい。これに決定です。なんなら GitHub Wiki のエンジンは Gollum らしいので、互換性 100%です。
ただし、画像の取り扱いについては注意が必要です。
GitHub Wiki は画像の取り扱いが面倒
Gollum Wiki では画像やファイルを挿入する際、のように、uploads ディレクトリにファイルを入れて相対パスを貼る方法が採用されています。つまり、編集画面から直接画像を挿入することができません。
GitHub Wiki も同じく、編集画面から画像をアップロードすることができません。これにはいくつかの対処方法があるようなのですが、以下の 3 つにまとめられそうです。
-
Wiki レポジトリを clone し、uploads ディレクトリを作成する
Wiki はレポジトリになっているので、それを clone して画像ファイルを作れば、相対パスで画像を貼ることができます。Gollum Wiki の使い方と同じですが、研究室全員で clone するのは大変そうなのでこれはパス。 -
issue を立てて画像をドラッグアンドドロップ
GitHub の Issue に画像をドラッグアンドドロップするとランダムで URL が生成されます。それを貼れば画像が表示されるという算段。ですが、画像をドラッグアンドドロップしまくって移行するのは無理なのでこの方法は諦めます。 -
画像用のレポジトリを作る
Organization 内に画像アップロード用のレポジトリを作り、ブラウザからいちいちアップロードする方法です。若干めんどくさいですが、Gollum と使い勝手は似ている＆移行がラク（uploads/hoge.jpgをhttps://github.com/[Organization名]/[レポジトリ名]/blob/master/hoge.jpgに置き換えるだけ）なので、この方法で行きます。
GitHub Education の申請・Organization (Teams) の作成
ここら辺を参考に、ラボのボスにGitHub Educationを申請してもらいました。
教育者割引または研究者割引に応募する
Organizationの作成・TeamsへのアップデートはGitHubのトップページからできます。
.md のインポート
まずは Wiki 用のレポジトリを作成しましょう。今回はシンプルに wiki という名前にします。
wiki レポジトリ内の wiki も実は git レポジトリになっています (ややこしい) 。なので、そのままそれをクローンしましょう。
cd ~/
git clone https://github.com/organization/wiki.wiki.git
そしてこのディレクトリに、Gollum で使っていた.mdを突っ込みます。
cp ~/gollum/*.md ~/wiki.wiki
これらを add, commit, push すれば.mdのインポートは終了です！
cd ~/wiki.wiki
git add .
git commit -m "imported markdown files"
git push
画像用レポジトリの移行
次に、Gollum Wiki で使っていた画像・ファイルを GitHub Wiki にインポートします。
まずは、ファイルをアップロードするディレクトリを作成します。今回はuploadsという名前にしましょう。
cd ~/
git clone git@github.com:organization/wiki.git
cd wiki
mkdir uploads
そしてここに Gollum で使っていたファイルを突っ込みます... としたいところなのですが、GitHub には基本的に 100MB 以上のファイルをアップロードすることができません。LFS なんて知らない
なので、まずは 100MB 以上のファイルを避難させます。
cd ~/gollum-uploads
ls -sh | grep [1-9][0-9][0-9]M
mv large.mp4 large.pdf large.tar.gz ~/over-100mb/
避難させたファイルは NAS にでもあげておきましょう。
これができたらファイルをレポジトリにあげます。
cp ~/gollum-uploads ~/wiki/uploads
cd ~/wiki/uploads
git add uploads
git commit -m "imported files smaller tha 100mb"
git push
もしファイルが大量にあるような場合は、適宜分割して add&commit&push しましょう。
最後に、.mdファイル内でファイルを参照するパスが Gollum の相対パスのままなので、これを置き換えましょう
cd ~/wiki.wiki
sed -ie 's@uploads/@https://github.com/AoyamaLab/wiki/blob/master/uploads/@g'
git add .
git commit -m "changed path to uploads"
git push
これで完了です！きちんと GitHub Wiki で動いているか確認しましょう。
快適な研究室Wikiライフを！