インストール

1. 動作環境

1.1 必要な Python ライブラリ

Python 3.12 で開発・動作確認しています。依存ライブラリは以下の通りで、本体のインストール時に requirements.txt からまとめて導入できます。

1.2 オプション

以下は無くても ClimCanvas は動作します。必要に応じて追加してください。

1.3 Python の環境構築

ClimCanvas は可視化ツールであり、利用者はその前段で Python によるデータ解析を行っていること — つまり自分の Python 環境を既に持っていることを前提にしています。その環境が共用のものか、自分で作った conda / venv 環境かは問いません。普段の解析に使っている環境に、依存ライブラリ (1.1) を追加すればそのまま使えます。

1.3.1 既存の仮想環境に足す場合

その環境を activate してから、本体一式に同梱の requirements.txt で入れます (本体の置き場所 $IDIR/climcanvas は 2.1)。conda 環境なら、下の conda create と同じパッケージ列を conda install -c conda-forge で入れても構いません (cartopy は conda-forge から入れるのが確実です)。

1.3.2 新しく仮想環境を作る場合

ClimCanvas 用に新しく作る例です。cartopy は地理ライブラリ (GEOS・PROJ) に依存するため、conda-forge からまとめて導入するのが確実です。"proj<9.8" は cartopy の既知の不具合 (PROJ 9.8 との組み合わせで海岸線が緯度方向にずれる) を避けるための一時的な固定で、cartopy 側の修正が公開されたら外して構いません。

本体一式に同梱の environment.yml を使うと、動作確認済みのバージョン構成 (上記の固定を含む) の環境を1コマンドで作れます。

2. 本体のインストール

ClimCanvas 本体は Python 環境に組み込む (pip install する) パッケージではなく、インストールは任意の場所にディレクトリを置くだけです。

インストールの形は3つあり、併用もできます (例: 管理者の共有インストールがあるサーバーに、自分用のクローンを別に持つ)。リモート環境でのポートの保護 (3.2) はコードの置き場所と無関係に効くため、どの形でも安全性は変わりません。

2.1 自分でインストールする場合

手元の PC でもサーバーでも手順は同じです。依存ライブラリ込みの Python 環境 (1.3) ができていれば、本体を置くだけで起動できます。GitHub のリポジトリ (ClimCanvas/ClimCanvas) をクローンするだけです。

以後、本体一式は $IDIR/climcanvas に置かれます (app.py のあるディレクトリ = $IDIR/climcanvas)。git clone の末尾の climcanvas は展開先のディレクトリ名で、省略すると ClimCanvas (大文字始まり) になります。このサイトでは小文字の climcanvas で統一しています。

• クローンすると常に最新版になります。公開リポジトリには版ごとに 1 つのコミットしか無く、main の先頭が常に最新の版です。GitHub の Releases 欄の「Latest」は DOI を付けた版にだけ付くので、最新版の目印にはならないことに注意してください。
• 使っている版の確認: アプリの見出しの下に ver 1.02.1 のように表示されます。再現スクリプトの 1 行目にも書かれます。

特定の版を使う: 版はタグ (v1.00 など) で選べます。以前使った版を再現するときなど、--branch にタグ名を指定してクローンします。

更新する: 普通にクローンしたもの (main) は git pull で最新版になります。タグを指定したクローンは git pull ではなく、タグを取り直してから切り替えます。

git を使わない場合: GitHub の「Tags」ページにある各版の Source code (zip) をダウンロードして展開し、そのディレクトリを $IDIR/climcanvas として置きます。更新は新しい版の zip を展開して置き換えます。

2.2 管理者がインストールする場合 (サーバーでの共有インストール)

複数人で使うサーバーでは、管理者が1箇所に共有インストールする形が管理も安全性も楽です。手順は 2.1 と同じで、置き方だけが違います。

• 共有場所に、読み取り専用で置く (例: /opt/climcanvas、所有は root)。利用者に必要なのは読み取り+実行権限だけです。利用者に書き込みを許すと、悪意あるユーザーがコードを書き換えて他の利用者に (その人の権限で) 実行させる経路になるため、必ず読み取り専用にします。
• Python 環境も共有できます。conda 環境などを全員が読める場所に作れば、利用者ごとの環境構築は不要です。
• 更新は管理者が一度だけ。共有コードを更新すれば全員に反映され、バージョンが利用者間でばらつきません。
• 利用者のデータは混ざりません。設定・セッション・プリセット・カスタムカラーマップは各利用者のホームの ~/.climcanvas/ に保存されるため、コードを共有しても利用者ごとに分離されます。

3. リモート環境での設定

サーバーに置いてリモートで使う場合の設定です。インストールを自分で行ったか管理者が行ったか (2.1 / 2.2) には関わりません。3.1 の考え方はリモート利用のすべてに当てはまります。3.2 は複数人で使い利用者間のデータ分離が必要な場合に管理者が行う追加設定、3.3 は利用者が自分で行う設定 (config.toml の運用形態と開けるデータの範囲) と起動です。

3.1 前提: ClimCanvas のセキュリティの考え方

ClimCanvas 自体にはログイン機能がなく、守りは OS の仕組みに任せる設計です。推奨は「利用者ごとに、自分の SSH アカウントで自分の ClimCanvas を起動する」構成で、柱は次の3つです。

• 認証は SSH に任せる: --server.address=127.0.0.1 で起動してポートをネットワークに公開せず、接続は SSH トンネル経由に限ります。
• 権限は OS パーミッションに任せる: 共有の1プロセスを全員で使うのではなく、各利用者が自分の権限でプロセスを起動します。アプリが読み書きできるファイルは、OS によって起動者本人の範囲に制限されます。
• 開けるデータを絞る: 設定ファイルの allowed_dirs (3.3) で、開ける netCDF をデータ置き場の配下だけに制限します。

ここまでは利用者が各自で行えるため、管理者の作業はありません。

3.2 サーバー管理者がすること: 利用者ごとのポートの割り当てと保護

上の構成には、OS では守れない穴がひとつ残ります。127.0.0.1 はサーバーの外からの接続を防ぎますが、同じサーバーに SSH ログインできる別の正規ユーザーには効きません。Streamlit は無認証なので、ポート番号を試して他人の ClimCanvas に接続できてしまうと、起動した本人の権限でファイルを読み書きできてしまいます。「アカウントを持つメンバー同士は互いにデータを見せてよい」と言える環境ならこのままでも問題ありませんが、利用者間のデータ分離が必要な場合は、管理者 (root) がファイアウォールの owner マッチを設定します。各ポートに「接続してよいのは割り当てた本人だけ」という鍵を掛け、他ユーザーによるポート探索そのものを無効化するためです。

同梱のスクリプト (scripts/server/) で、ポートの割り当てと保護ルールの適用が1コマンドにまとまっています (対象は Linux サーバー)。

• ポートは、--port N を指定しなければ範囲 8501〜8600 (環境変数 CLIMCANVAS_BASE_PORT / CLIMCANVAS_MAX_PORT で変更可) から空きポートが自動で選ばれます。
• 割り当ては台帳 /etc/climcanvas/ports.tsv に userA<TAB>8501 の形式で1行追加され、実行のたびに台帳全体からファイアウォール (nftables) のルールを再生成して適用します。古い割当やルールの重複は残りません。
• 割り当てたポート番号は、利用者に一度だけ通知してください。利用者は手元 PC からの SSH トンネルの行き先にこの番号を使います (割り当てが 8505 なら ssh -L 8501:localhost:8505 …。前半の 8501 は利用者の PC 側のポートで、空いていれば何番でもかまいません)。assign の実行時に、その利用者向けの接続手順 (① 手元で ssh → ② サーバーでランチャ → ③ ブラウザ、ポート番号入り) が表示されるので、それをそのまま渡せば済みます。割り当ては固定なので通知は最初の一度で足ります。
• 利用者が scripts/server/start-climcanvas.sh で起動すると、台帳から自分のポートを自動で引くため、サーバー側の起動コマンドにポート番号やオプションを書く必要はありません (手元 PC 側のトンネルには通知されたポート番号を使います)。手動起動でポートやオプションを誤ると保護が効かなくなるため、利用者にはランチャからの起動を強く推奨してください。

ルールの永続化 (サーバー再起動対策)

適用されたルールはカーネルのメモリ上にしかないため、サーバーを再起動すると消えます (台帳と生成物のファイルは残ります)。そこで、起動時に生成物 /etc/climcanvas/climcanvas.nft を読み込み直す仕掛けを一度だけ作っておきます。Debian / Ubuntu では、起動時に nftables.service が /etc/nftables.conf を nft -f で読み込むので、そこに include を1行足すだけです。

• 以後 assign / remove のたびに climcanvas.nft は書き直されるため、include の行を触り直す必要はありません (次回の起動時も常に台帳の最新状態が復元されます)。
• RHEL / AlmaLinux 系は設定ファイルが /etc/sysconfig/nftables.conf ですが、追記する行と systemctl enable nftables は同じです。
• サーバーが firewalld や ufw で管理されている場合は、nftables.service の有効化が管理の競合を招くことがあります。代わりに nft -f /etc/climcanvas/climcanvas.nft を実行するだけの小さな systemd ユニット (または @reboot の cron) を作る方が安全です。
• 生成物は専用テーブル (inet climcanvas) だけを作り直す形式なので、include しても既存のファイアウォール設定を上書きする心配はありません。

3.3 ユーザーがすること

3.3.1 ~/.climcanvas/config.toml の設定

利用者側の設定は、サーバー上の自分のホームにある ~/.climcanvas/config.toml に書きます。設定ファイルの詳細を参照し、allowed_dirs 、session_dirs 、mode の3点を編集します。リモート運用ではまず mode = "remote" を設定してください。ClimCanvas のUIがリモート運用向けに変わります。未設定のままでは常にローカル運用向けの表示になります。具体的には、"remote" にすると、セッションの青タブが「サーバーから/サーバーへ」、編集中セッションのバナーが「サーバー内のセッション」と表示され、保存先がサーバー側か手元 PC 側かを取り違えにくくなります（詳しくは進行中の作業 (セッション) の保存と復元）。

3.3.2 セッションの保存先の設定

次に進行中の作業 (セッション) の保存先ディレクトリを設定します。UI の「保存先ディレクトリ」の選択肢になります。未設定なら~/.climcanvas/sessions の1つだけになります。

3.3.3 データ読み込み許可ディレクトリの設定

リモート運用では、ユーザーがブラウザからnetCDFファイルを開く時に、サイドバーの「参照...」ボタンが使えません。このボタンは OS のファイル選択ダイアログを開きますが、ダイアログが開くのはアプリを動かしているマシン (サーバー) の画面であり、手元 PC のブラウザには何も起きないためです (FAQ: 「参照...」ボタンが無い。押しても何も起きない)。そのため、リモート運用では設定ファイルの allowed_dirs でデータ読み込み許可ディレクトリを設定することが実際上必須です (設定ファイルの詳細)。設定すると「参照...」は非表示になり、代わりにサイドバーの「新規作業」と「ファイルの追加」(および各ファイルの「座標ファイル (任意)」欄) に、ブラウザ内でフォルダを辿ってファイルを選べる「許可ディレクトリから選ぶ」が現れます。

この設定はデータ保護の観点からも都合がよく、開ける netCDF が許可ディレクトリ配下に限定され (配下以外のパスはエラー)、複数人で使うサーバーで利用者が開けるデータの範囲を明示的に決めておけます。

3.3.4 許可ディレクトリの3つの指定方法

許可ディレクトリの指定方法は3つあります。恒常的な設定は config.toml、その1回の起動だけ変えたいときは環境変数、と使い分けます。

優先順位は CLIMCANVAS_ALLOWED_DIRS (ランチャ経由のみ) > CC_ALLOWED_DIRS > allowed_dirs (config.toml) で、どれも未設定なら制限なしです。環境変数は設定されていれば空でも config.toml に勝ちます。ランチャ経由では、CLIMCANVAS_ALLOWED_DIRS が指定されているときだけ CC_ALLOWED_DIRS を上書きして引き渡します。

3.3.5 起動

設定ファイル~/.climcanvas/config.toml の編集が終わったら、インストール作業は終了です。接続の流れは使い方 — リモート運用を参照してください。ポート割り当て (3.2) を使うサーバーでの起動には、使い方 — リモート運用 1.4を参照してください。

3.4 まとめ: 何を設定し、何のためか

4. ライセンス・免責・引用・外部との通信

4.1 ライセンス

ClimCanvas は GNU Affero General Public License バージョン 3 (AGPL-3.0-only) で公開するオープンソースソフトウェアで、いかなる保証もありません (ライセンスの第 15 条・第 16 条)。全文はリポジトリの LICENSE、ClimCanvas 固有の追加条項は LICENSE.exception にあります。要点は次のとおりです。

• ClimCanvas が生成した再現スクリプトと、図・アニメーション・セッションなどの出力物は利用者のものです。AGPL は及びません。
• 改変したものを配布したり、他の人向けにネットワーク越しに動かしたりするときは AGPL の条件 (ソースコードの提供など) に従ってください。無改変で使う分、自分で使う分には義務はありません。
• 「ClimCanvas」の名称とロゴは改変版には使えません。

4.2 図の検証は利用者の責任です

ClimCanvas が生成した図が意図したものを示しているか (どのレベル・時刻を選んだか、どの範囲をどう平均したか、欠損をどう扱ったか等) の確認は利用者の責任です。数値上の前提はマニュアルの計算の前提に、論文投稿前の確認手順は論文投稿前の確認にまとめています。図の値に影響するバグが見つかったときは、影響する版と機能をリポジトリの KNOWN_ISSUES.md に掲載します。論文等で引用する場合は、使った版を付けて引用してください (引用情報は CITATION.cff)。

4.3 外部との通信

ClimCanvas 自身はネットワークに何も送りません。例外は次の 2 つです。

• 地理データのダウンロード: 海岸線・国境・陸域の Natural Earth データは、初めて使う縮尺のものを cartopy が自動でダウンロードします (ネット接続が必要。取得後は cartopy のキャッシュに残ります)。
• Streamlit の利用統計: 画面の表示に使っている Streamlit は、既定で匿名の利用統計を開発元に送信します。止めるには、アプリを動かすマシンの ~/.streamlit/config.toml に次を書きます。

4.4 引用

ClimCanvas を論文等で引用するときは、使った版を明記して引用してください。

• 使った版の確認: アプリ右上のメニューの About、または再現スクリプトの 1 行目に版 (1.00.1 など) が書かれています。
• concept DOI 10.5281/zenodo.22997360: 全版共通で、常に最新のアーカイブに解決します。ソフトウェア全体を指すとき、および使った版に版 DOI が無いときはこれを使い、版番号を併記してください。
• 版 DOI: 特定の版のアーカイブを指します。DOI を取るのは節目の版 (v1.00 と、論文で使う版) だけで、それ以外の版は git のタグのみです。版 DOI がある版: v1.00 = 10.5281/zenodo.22997361。
• 引用のメタデータはリポジトリの CITATION.cff にあり、GitHub のリポジトリページの「Cite this repository」から APA / BibTeX 形式で取れます。