Runme runs Markdown: runme.dev を始めてみた

tl;dr

• stateful/runme: Execute your runbooks, docs, and READMEs.
• 先日 jupyter notebook をいじってたら 自己紹介 されたｗ
• 雑に言えば jupyter notebook の bash kernel 代替みたいなツール
• GO で書かれていて markdown ファイル（.mdなど）のコードブロックを実行可能なランブックにできる
• 各種コマンドやツールの使い方や記述方法の記録に使い始めた
• python に依存しないでいい分だいぶ楽？

runme.dev is 何

先に書いたように jupyter notebook の bash kernel 代替って理解で特に問題なさそう。

https://runme.dev/

こんな感じの普通のマークダウンファイルのコードブロックを

こんな感じで jupyter notebook みたいに実行して結果を表示してくれる感じのツール。

jupyter notebook is 何

jupyter notebook は python で動いていて、大体 python を動かすツール。

https://jupyter.org/

google だと Colaboratory も裏は jupyter （のはず？）

DataDog だと Notebook も裏は jupyter （だよね？）

AWS SageMaker notebooks も jupyter notebook ね。

いずれもテンプレート等が違うだけで python に jupyter 用の bash kernel をインストールしてあげれば python だけじゃなくて bash が動かせる、みたいな建付け。

vs

jupyter notebook

• jupyter notebook は python に依存していて、実行環境のバージョンに左右される（複数のバージョンの python を使っているとちょっと面倒）
• つまり自分だけが使うなら問題ないし、共通環境下でチームで使うなら問題ないけど、各自のローカル環境で共有して使う時はバージョンの統一とかコードの書き方の注意とか、細かいところで注意が必要（実際のところ機械学習の文脈ではそう気にすることもないはず）
• ファイル自体は json っぽい形式のファイルになっているので、git でのコード管理はできる
• 拡張子は .ipynb なので jupyter だと（１回覚えれば）わかる
• 初見の人にはなんだこれ？になりがち。テキストとして開くと json だし jupyter のインストールや環境整備が必要になる（前述の python のバージョン等の問題になる）
• 誤解を恐れず雑に言うなら機械学習のためのpythonコードを共有するには最適だけど、それ以外では使い方に迷う

runme.dev

• runme は Go で書かれていて、バイナリを１つインストールするだけなので、環境にはあまり左右されない
• 既存の markdown ファイルと 100% の互換性を謳っているので、実行バイナリ以外に必要なものもなく、markdown の知識だけでだいたいいける
• front matter が勝手についてくるのと、コードブロック（```三点バッククォート）にちょっと書き足しが要る
• 初見の人にもファイルとしてはただの markdown として見てもらうことができ、コードブロックの実行の恩恵を受けたいなら runme をインストールすればいいだけという手軽さ
• runbookとして使いたい人にはだいたい何にでも使えて、使わない人の邪魔にもならない

other

• 世の中には他にもたくさんの類似ツールがあって、それぞれ特色があったりするので調べたら教えてくださいｗ

個人の感想

• jupyter notebook の管理でちとハマった。WSL2 に python が 2.7,2.8,3.8,3.10,3.11,3.12 とやたら入っていて、自分でもどれやねんってなっている（brewでインストールしていてanacondaやpyenvを使っていないのが悪い）
• やりたいことは aws cli や jq 等のツールのコード例の管理やその実行結果の確認、再利用のための記録を残すこと、だったので、jupyter notebook の bash kernel で一旦問題なかった
• jupyter は前述のとおり各自の環境に依存しやすいし、ランブックやコードの共有という文脈では、チームで使うツールとしてはいまいちかなって思った
• そんな時にタイミングよく runme.dev から X 上で自己紹介を受けたのでちょこっと触ってみたところ、見た目のダメっぽさ（jupyter準拠？）は jupyter notebook とほとんど変わらず、機能的には bash kernel と同じようにトンネルしてるのと変わらない、コード的にはマークダウンとして扱うだけ、インストールすれば使えるし、使いたくなければ使わなくてもそんなに困らない（コピペで自分で実行するなら要らない訳だ）
• まだドキュメント全部を試していないけど、マークダウンファイルを runbook として扱うワークフローも作れるし、github actions を呼び出す等もできるので、業務用のリポジトリに配置してサービス向けのドキュメントとして扱うこともできそう
• よくある◯◯百本ノックみたいな記事のコード部分を乗っけておいてボタンポチで実行結果が確認できるのに使えるかもとか（だいたいそんな感じに使うつもりで使っている）

終わりに

まだリポジトリのスターも少ないし日本語の記事が全然見当たらなかったので、とりあえず始めてみた記事を用意してみようかなと。
個人利用で知見を集めつつ、SREやインフラの文脈で runbook としてチームに採用できたらいいな、とか。

おまけ（追記）

こんな感じで VS Code でマークダウンファイルを開いておいてボタン１つで実行できる

runme で開いて左端の実行ボタンで実行するとエディタ内に出力される（この出力結果を保存できたりするらしい）