USAGE / REMOTE

使い方 — リモート運用

研究室サーバー等のリモートマシンで ClimCanvas を動かし、手元 PC のブラウザから操作する場合の手順です。アプリ・netCDF データ・セッション保存先はすべてサーバー側にあり、手元にはブラウザの画面だけが届きます。作成した図 (PNG など)・動画・再現スクリプトの保存は、ブラウザ経由で手元 PC へダウンロードする形になります。手元の PC で完結させる場合はローカル運用を、1台の PC に複数人で接続する一時的な利用は演習・デモ運用を参照してください。

REMOTE

リモート運用

利用者ごとに自分の ClimCanvas に SSH で接続。データも権限も互いに分離。

1. アプリの起動方法 (接続の流れ)
2. 進行中の作業 (セッション) の保存と復元

1. アプリの起動方法 (接続の流れ)

接続には SSH トンネル (ポート転送) を推奨します。認証と暗号化を SSH に任せられるため、Streamlit のポートをネットワークに公開せずに済みます。まず 1.1 で基本の接続の流れを説明し、1.2 と 1.3 で毎回の起動を楽にする設定 (Streamlit の設定ファイル・シェル関数) を紹介します。次に 1.4 で、管理者がポートを割り当てている共用サーバーでの、より保護の強い起動方法を説明します。リモート運用では実際上必須になる、データ読み込み許可ディレクトリの設定はインストール 3.3 にあります。

1.1 接続の基本の流れ

1本の SSH セッションが「ログイン」と「トンネル」を兼ねる、いちばん簡単な流れは次の通りです。

# ① 手元 PC のターミナルで — トンネルを張りつつサーバーへログイン

$ ssh -L 8501:localhost:8501 you@server.example.ac.jp

# ② ログインしたサーバー上で — Python 環境を activate してアプリを起動 ($IDIR = インストール先ディレクトリ)

$ conda activate 環境名 # 普段の解析環境 (インストール 1.3)

$ cd $IDIR/climcanvas

$ streamlit run app.py --server.headless=true --server.address=127.0.0.1

# ③ 手元 PC のブラウザで http://localhost:8501 を開く

-L 8501:localhost:8501 は -L PC側のポート:localhost:サーバー側のポート で、「自分の PC の 8501 番に来たものを、SSH 暗号トンネルでサーバーの localhost:8501 番に転送して」という意味です。
前半 (PC 側) のポートは、手元 PC で空いてさえいれば自由に変えられます (例: -L 8502:localhost:8501 — ブラウザで開く URL も http://localhost:8502 になります)。一方、後半 (サーバー側) は Streamlit が実際に待ち受けている番号を指すため、サーバー側の起動と一致している必要があります (既定は 8501。変える場合は起動側に --server.port を付けて合わせます)。
conda activate 環境名 は、依存ライブラリを入れた普段の Python 環境 (インストール 1.3) に切り替える操作です。SSH 直後のシェルは既定の環境なので、忘れると streamlit コマンドが見つからないか、依存の入っていない python で起動して失敗します。
streamlit run app.py --server.headless=true は「streamlit を使って app.py を起動。ただし、サーバー側で画面 (ブラウザ) を自動で開かないようにする」という意味です。
--server.address=127.0.0.1 を付けると、Streamlit はサーバー機の中から来た接続しか受け付けません。ネットワークから直接は見えなくなり、SSH 認証を通った人だけがhttp://サーバーのIP:8501 に繋げることができます。
手元 PC のブラウザで http://localhost:8501 を開くと、SSH 暗号トンネルを通って、サーバーの localhost:8501 に繋がります。
注意: ①のターミナルを閉じる (SSH が切れる) と、トンネルと一緒に Streamlit 本体も止まることに注意して下さい。
トンネル1本で同時に複数の接続を通せます。同じ URL をブラウザで2タブ開けば、同じアプリに対して独立した2つのセッションになり、別々の図を並行して作れます (画面・パネル設定は互いに混ざりません)。

1.2 起動オプションを毎回打たずに済ませる (~/.streamlit/config.toml)

1.1 の②の2つのオプションは、サーバー側の自分のホームに Streamlit の設定ファイルを置いておけば省略できます。以後、起動は streamlit run app.py だけで済みます。

# ~/.streamlit/config.toml (サーバー側に置く — 自分のアカウントにだけ効く)

[server]

headless = true

address = "127.0.0.1"

優先順位は「コマンドラインのオプション > 環境変数 > 設定ファイル」です。一時的に変えたいときは --server.port=8503 のようにオプションで上書きすればよく、後述のランチャ運用 (必要なオプションを明示して起動する) に移行しても、このファイルが邪魔をすることはありません。
ClimCanvas 本体の設定ファイル ~/.climcanvas/config.toml (設定ファイルの詳細) とは別物です。ファイル名は同じ config.toml ですが、こちらは Streamlit 自体が読む設定です。

1.3 どのディレクトリからでも起動できるようにする (シェル関数)

streamlit run は app.py を絶対パスで指定すれば、どのディレクトリからでも起動できます (Streamlit が app.py のあるディレクトリを自動で import の検索パスに加えるため)。ただし作業ディレクトリ (カレントディレクトリ) は起動した場所のままなので、「netCDFファイルのパス」欄の初期値 data/sample/sample_atmos.nc や、再現スクリプトの相対パス形式 (FAQ) は起動した場所を基準に解釈されます。そこで、インストール先へ cd してから起動するシェル関数を ~/.bashrc に書いておくのがおすすめです。python をフルパスで書けば conda activate も不要になります。書くのはこのページの呼称 $IDIR ではなく実際のパスにしてください (以下は ClimCanvas が $HOME/climcanvas、Python 環境が $HOME/miniforge3/envs/myenv にある場合の例)。

# ~/.bashrc に追記 (サーバー側。zsh なら ~/.zshrc)。2 つのパスは自分の環境に合わせる

climc() {

( cd "$HOME/climcanvas" && \

"$HOME/miniforge3/envs/myenv/bin/python" -m streamlit run app.py \

--server.headless=true --server.address=127.0.0.1 \

--server.port="${1:-8501}" )

}

# 起動 (どこからでも。cd も activate も不要)

$ climc # ポート 8501 で起動

$ climc 8502 # ポートを変える (手元 PC 側のトンネルの行き先も合わせる)

管理者がポートを割り当てている共用サーバー (1.4) では、この関数ではなくランチャを使い、どこからでも起動したい場合はランチャを alias にします (1.4)。

1.4 管理者がポートを割り当てている場合 (start-climcanvas.sh)

複数人で使うサーバーで、管理者が利用者ごとのポートを割り当てている場合 (インストール — リモート環境での設定) は、同梱のランチャで起動します。ランチャは台帳から自分のポート番号を自動で引き、保護に必要なオプションを揃えて起動します。手元 PC 側のトンネル (①) の行き先 (後半の数字) には自分のポート番号を使います (割り当ては固定なので毎回同じ番号です。前半の PC 側のポートは 1.1 と同じく自由です)。手動で起動することもできますが、ポートやオプションを誤ると保護が効かなくなるため、安全のためランチャからの起動を強く推奨します。

# ① 手元 PC のターミナルで — 自分のポート番号 (例: 8505) へトンネルを張りつつログイン

$ ssh -L 8501:localhost:8505 you@server.example.ac.jp

# ② ログインしたサーバー上で — Python 環境を activate してランチャで起動 (ポートは台帳から自動)

$ conda activate 環境名 # ランチャは PATH 上の python3 (activate 中の環境) を使う

$ cd $IDIR/climcanvas

$ scripts/server/start-climcanvas.sh

# ③ 手元 PC のブラウザで http://localhost:8501 を開く

自分のポート番号は割り当て時に管理者から通知されます。忘れた場合は、先にサーバーへ普通に (トンネルなしで) ログインしてランチャを起動すれば、「ssh -L 8501:localhost:(自分のポート) …」の形でそのまま使える接続コマンドが表示されるので、それを手元 PC の別ターミナルで実行してからブラウザを開けば大丈夫です。
起動コマンドは、環境の種類 (conda / venv / システム python) にも ClimCanvas の置き場所 (自分でインストール / 管理者がインストール) にもよらず同じです。システム python に依存を入れている場合は activate は不要です。
開ける netCDF をその1回の起動だけ絞りたい場合は、CLIMCANVAS_ALLOWED_DIRS を付けて起動します (インストール 3.3)。

使う python を明示したい場合 (activate を省く)

環境を activate せずに起動したいときは、CLIMCANVAS_PYTHON に自分の環境の python をフルパスで指定します。~/.bashrc 等に書いておけば、以後は activate なしで上の②と同じコマンドだけで起動できます。

# ~/.bashrc に1行 (以後のログインで常に有効)

export CLIMCANVAS_PYTHON=$HOME/miniforge3/envs/myenv/bin/python

# 起動 (activate 不要)

$ cd $IDIR/climcanvas

$ scripts/server/start-climcanvas.sh

もっと手軽に起動したい場合 (alias / PATH)

ランチャは app.py の場所を自分自身 (スクリプトファイル) の位置から解決するため、どのディレクトリからでも起動できます。~/.bashrc に alias か PATH を設定しておけば、cd も不要になります。書くのはこのページの呼称 $IDIR ではなく実際のパスにしてください (以下は /opt/climcanvas にある場合の例)。

# 方法1: alias (~/.bashrc に1行) → 以後どこからでも climc で起動

alias climc='/opt/climcanvas/scripts/server/start-climcanvas.sh'

# 方法2: PATH に追加 (~/.bashrc に1行) → 以後どこからでも start-climcanvas.sh で起動

export PATH="/opt/climcanvas/scripts/server:$PATH"

参考: ランチャの環境変数一覧

環境変数	既定	用途
`CLIMCANVAS_PYTHON`	`python3`	使う python 実行ファイル。環境を activate せずに起動する場合にフルパスで指定 (上記。アプリと生成スクリプトの実行環境を揃えたいときにも有用)
`CLIMCANVAS_ALLOWED_DIRS`	(なし)	開ける netCDF のディレクトリ (`:` 区切り)。そのプロセスに限り設定ファイルの `allowed_dirs` を上書き (インストール 3.3)
`CLIMCANVAS_APP_DIR`	スクリプト位置の2つ上 (リポジトリ直下)	`app.py` のあるディレクトリ。スクリプトをリポジトリの外へコピーしたときだけ指定が必要
`CLIMCANVAS_PORTS_TABLE`	`/etc/climcanvas/ports.tsv`	ポート台帳のパス (通常は変更不要)

2. 進行中の作業 (セッション) の保存と復元

セッションファイルは、読み込んだ netCDF のパス・パネル構成・描画設定など作成した図の設定一式を 1つの JSON ファイルにしたものです。これを保存することで、次回はその続きから始められます（復元）。リモート運用では「サーバー側に残すか、手元 PC に持ってくるか」で2つの方式を使い分けます。復元 (「セッション復元」) も保存 (「保存」→「セッション」) も「サーバー (青) / アップロード・ダウンロード (オレンジ)」の対のタブに分かれており、編集中のセッションの由来は、図の上の同じ色のバナーでいつでも確認できます。なお青タブを「サーバーから/へ」と表示させるには、サーバー側の config.toml に mode = "remote" を設定します (未設定ではローカル運用向けの「PC から/へ」表示)。

方式 A: サーバー内に名前を付けて保存 (日をまたいで再開する用)

保存: 「保存」→「セッション」→「サーバーへ」タブから。保存先はサーバー側で、手元 PC には何も残りません。
復元: 「データ・セッション読み込み」→「セッション復元」の「サーバーから」タブより。翌日以降も、同じサーバーに接続すれば起動直後の画面から再開できます。

保存・復元の挙動は、サーバー側の設定ファイルの session_dirs (設定ファイルの詳細) の有無で変わります。

session_dirs の指定が無い場合 (デフォルト): 保存先はサーバーの ~/.climcanvas/sessions/ の1箇所に固定です (フォルダは初回保存時に自動で作られます)。「保存先ディレクトリ」の選択肢は1つだけで、復元側にはディレクトリ選択自体が表示されません。
session_dirs を指定した場合: 保存先の候補を複数登録でき、保存・復元の両方でディレクトリを切り替えられます (復元側にも「ディレクトリ」選択が現れます)。プロジェクト共有ディレクトリを候補に入れれば、同じサーバーの共同研究者へセッションを引き継ぐこともできます。

方式 B: アップロード・ダウンロード

保存: 「保存」→「セッション」→「ダウンロード」タブの「セッションの保存」ボタンで保存。保存先はブラウザのダウンロード設定に従います。ファイル名は自由で、保存時に付けても保存後に変えても構いません (復元は任意の名前のファイルで行えます)。
復元: 「データ・セッション読み込み」→「セッション復元」の「アップロード」タブより、その JSON をアップロードします。別のサーバーの ClimCanvas に読ませることもできます。読み込み後はアップローダが「読み込み済み」表示に変わり、差し替えたいときは「別のセッションファイルを読み込む」を押してから再アップロードします。

復元時の注意

セッションの JSON に入っているのは netCDF のパスだけで、データ本体は含まれません。パスはサーバー上のパスなので、復元する側のサーバーの同じ場所に netCDF が置かれている必要があります (別サーバーへ持ち込む場合は特に注意)。
allowed_dirs を設定した環境では、復元時にもパスの検証が行われます。許可ディレクトリ外のパスを含むセッションはエラーになります。
サーバー内の保存はユーザーごとのホームに置かれます。別のユーザーでログインすると別の一覧になります。
「セッションファイル」欄はセッション専用です。個人プリセットの JSON は受け付けません (プリセットはサーバー側の ~/.climcanvas/preset.json に置くと起動時に自動適用されます)。

ファイルの読み込みについてマニュアルで詳しく → セッションの中身と注意点について詳しく →