Skip to content

Dev_Containers.ja.md

Latest commit

 

History

History
290 lines (203 loc) · 11.5 KB

Dev_Containers.ja.md

File metadata and controls

290 lines (203 loc) · 11.5 KB
Raw

開発コンテナ(Development Containers)の利用

このリポジトリでは 開発コンテナ(Dev Container)をサポートしています。 これを使うと、ローカルの環境を汚すことなく、RedAmberに必要なツール一式を含んだ環境を準備することができます。この環境には、Ruby、Apache Arrow、RedAmberのソースツリー、GitHub CI、サンプルデータセット、IRubyカーネルを含んだJupyter Labなどが含まれていて、簡単でメンテナンスしやすく、かつ再利用性が高い構成になっています。

RedAmber用のDev Containerは、.devcontainer ディレクトリに必要な設定が書かれています。現在の実装では、Dockerfileを使用せず、Dev Containers用のUbuntuベースイメージに、Dev Container Featuresを使って、Python、GitHub CIの環境を加えて作っています。Ruby は Container ができてから走らせるスクリプトでインストールしています。

Dockerfileで作るのと比べて、

  • User周りの設定を自動的にやってくれる
  • 言語環境をFeatureとして個別に追加することができる
    • PythonではJupyter Labをオプションとして追加できる
    • Rubyはrbenvをインストールしてあって後から別のバージョンを追加できる
    • Quartoを動かせる環境を簡単に追加でき、Jupyter notebookのソース管理に利用できる

等の利点があります。

ここでは代表的な利用法を2つ紹介します。

1. GitHub Codespacesでクラウド上のVMをブラウザから使う

必要なもの

GitHubアカウントにサインインしている必要があります。

注意

以下の手順では、Codespacesを起動するあなたのアカウントのクォータを消費します。GitHub Freeに対しては120時間/月・コア(2コアでは60時間)、ストレージ15GB/月が無料で使用できます。使用状況については Billing and plansのCodespacesの項を参照してください。

手順

  • GitHubのRedAmberのリポジトリを開いてください。

    • 開発を行う場合は、フォークしてご自身のリポジトリを作り、それを開いてください。

  • リポジトリ内の「<>Code」ボタン、「Codespaces」タブにある、「Create codespace on main」ボタンを押して新しいCodespacesを作成してください。

    • 既にCodespacesがある場合は、該当するコンテナ名をクリックすると再接続できます。

  • Codespacesの作成には時間がかかります。「View log」をクリックしてぼーっとログを眺めるか、コーヒーを淹れに行くとよいでしょう。

    • 今後、GitHub Container Registoryにキャッシュを保存して、速く起動できるようにする予定です。

  • VS Code for ブラウザでリポジトリが開きます。

    動作の確認は、下の動作の確認を参照してください。

詳細

より詳しくは、(GitHub Docs)リポジトリの codespace を作成するを参照してください。

2. ローカルにクローンしたリポジトリ―からDev Containerを立ち上げ、VS Codeで使う

必要なもの

  • Visual Studio Code (October 2020 Release 1.51以降)

    GitHub Codespaces 拡張機能をインストールして、GitHub 資格情報を使用してサインインする必要があります。GitHub Docs - GitHub Codespaces - 前提条件を参照して設定を済ませておいてください。

  • Docker

    • Windows

      Windows 10 Pro/Enterprise では Docker Desktop 2.0 以降。 Windows 10 Home (2004+) では、Docker Desktop 2.3 以降と WSL 2 バックエンド。

    • Mac

      Docker Desktop 2.0 以降

    • Linux

      Docker CE/EE 18.06 以降と Docker Compose 1.21 以降

  • Git

手順

  • ローカルに RedAmberリポジトリのクローンを作成します。

    • 開発を行う場合は、フォークしてご自身のリポジトリを作り、それをクローンしてください。
    $ git clone https://github.com/red-data-toolsまたは貴方のアカウント名/red_amber.git

    または、GitHub CLIで、

    $ gh repo clone red-data-toolsまたは貴方のアカウント名/red_amber

    とします。

  • 作成したローカルのリポジトリフォルダーをVS Codeで開きます。

    $ code red_amber

  • コンテナーで開く

    今のフォルダーをコンテナーで再度開きます。

    • 左下隅のステータスバーのリモートホスト表示（今はローカルなので「><」の後ろに何もついていない）をクリックするとリモートウィンドウを開くオプションが表示されるので、「コンテナーで再度開く」を選択します。

  • コンテナーの構築が開始されます

    最初の構築には、数分かかることがあります。それ以降の構築は高速になります。 構築が完了すると、左下隅のステータスバーのリモートホスト表示にコンテナー名が表示されます。

動作の確認

ターミナルでインストールされているツールを確認する

ターミナルが開いていない場合は、 CTRL + ` で開いてください。

下記のコマンドを実行して、ツールがインストール済みであることを確かめてください。

$ ruby -v --jit
$ rbenv versions
$ gem -v
$ gem list
$ bundler -v
$ iruby -v

$ python --version
$ pip --version
$ pip list
$ pipenv --version
$ jupyter --version
$ jupyter kenelspec list

$ git -v
$ git config user.name
$ gh --version

ユーザーは、vscode という名前で、uid/gid はローカルのユーザーと同じになっています。

$ id

RedAmberのテストを走らせてみる

$ bundle exec rake

REPLでRedAmberを試す

プリロードされたデータセットを使って、irbの環境でRedAmberの動作を確認できます。初回はRed Datasetsのデータをロードするため少し時間がかかります。

$ rake example

(snip)

    81: # Welcome to RedAmber example!
    82: # This environment will offer these pre-loaded datasets:
    83: #   penguins, diamonds, iris, starwars, simpsons_paradox_covid,
    84: #   mtcars, band_members, band_instruments, band_instruments2
    85: #   import_cars, comecome, rubykaigi, dataframe, subframes
 => 86: binding.irb

irb(main):001:0>

irbの動作を途中で止めているので、ここで表示されているデータセットが変数に読み込まれています。

irb(main):001:0> import_cars
=>
#<RedAmber::DataFrame : 5 x 6 Vectors, 0x0000000000010914>
     Year    Audi     BMW BMW_MINI Mercedes-Benz      VW
  <int64> <int64> <int64>  <int64>       <int64> <int64>
0    2017   28336   52527    25427         68221   49040
1    2018   26473   50982    25984         67554   51961
2    2019   24222   46814    23813         66553   46794
3    2020   22304   35712    20196         57041   36576
4    2021   22535   35905    18211         51722   35215

名前空間のRedAmber はインクルードされています。

irb(main):002:0> VERSION
=> "0.5.0"
irb(main):003:0> Arrow::VERSION
=> "12.0.1"

@を入力すると最初のブレークポイントに戻ることができます。

exit を入力するとirbを抜けます。

Jupyter LabでRedAmberを試す

Python と IRuby カーネルを持ったJupyter Labをブラウザで起動することができます。

$ rake jupyter

で、ローカルの8888ポートでブラウザが立ち上がります。

  • Notebookフォルダーとして、doc/notebook が割り当てられていて、そこには2つの.ipynbファイルがあります。
    • red_amber.ipynb : README.md で紹介している操作例。
    • examples_of_red_amber.ipynb : 様々な例を集めたもの。
  • require 'red_amber' は lib 以下のソースを読み込んでいます。

Quarto によるドキュメント操作

Quartoはオープンソースの科学技術ドキュメントの出版システムです。

この環境では、RedAmber の動作例を活用するために Quarto CLI を使っています。

---
title: Quartoを利用したドキュメント管理
---
flowchart LR
    id1["Source management
        (.qmd)"]
    id2["Analyze and edit by JupyterLab
        (.ipynb)"]
    id3["Publish document
        (.pdf)"]

    id1 -- convert --> id2 -- convert -->  id1
    id2 -- render --> id3
    id1 -- render --> id3
Loading
  • Quartoのドキュメント qmd 形式でソース管理できます。
  • .qmdファイルを Jupyter notebook ファイル(.ipynb)に変換して、 Jupyter Lab上で編集したりデータ解析ができます。
  • pdf形式 に変換することができます。

Quarto の動作を確認する

Quarto のバージョンと動作環境をチェックするには次のようにします。

$ quarto -v
$ quarto check

ヘルプを表示するには下記のようにします。

$ quarto --help
$ quarto render --help

ソースからJupyter Notebookを生成する

.qmdソースファイルから .ipynb を生成するには、

$ bundle exec rake quarto:convert

とします。doc/qmdフォルダー以下にあるqmdソースファイルから doc/notebookフォルダーにipynbノートブックファイルが作成されます。

より一般的には、

$ quarto convert ソースファイル.qmd
$ quarto convert ソースファイル.qmd --output 出力先ノートブック.ipynb

上の書き方では、出力ファイルはソースファイルの拡張子を .ipynbに変えて、ソースファイルと同じディレクトリに保存されます。

下記のコマンドは、Notebookを作成後、Jupyter Labを開きます。

$ bundle exec rake jupyter

Jupyter Notebookファイルをqmd形式で保存する

編集したJupyter Notebookをqmd形式に変換できます。

$ quarto convert ノートブック.ipynb
$ quarto convert ノートブック.ipynb --output 出力先ソースファイル.qmd

その他の活用方法

下記のコマンドはdoc/qmdフォルダー以下にあるqmdソースファイルをipynbに変換し、実行してpdfを作成します。

$ bundle exec rake quarto:test

下記はdoc/notebookフォルダーを含めたrakeの生成物を消去します。

$ rake clean

Quartoについてより詳しくは、コマンドラインヘルプ(quarto --help)、またはQuarto公式ページをご覧ください。

謝辞

Quarto の利用は、西田孝三さんの2022年度のRubyアソシエーション開発助成事業プロジェクト『RubyDataエコシステムへのQuartoの導入とその利用の促進のためのコミュニティ活動』 がきっかけとなりました。この場をお借りして感謝申し上げます。