Moodle ＋ JupyterHub 連携システム シリーズ（９）
9．トラブルシューティング
9.1 ログの取得
ログの精査はトラブルシューティングの第一歩です．ここでは，本システムにおけるログの取得方法を解説します．
9.1.1 JupyterHub のログ
通常，JupyterHub の stdout/stderr メッセージ は /var/log/messages にも出力されます．まずは JupyterHub サーバ上で /var/log/messages を確認してください．
/var/log/messages に JupyterHub のメッセージが出力されていない場合，または /var/log/messages が存在しない（Ubuntu の場合） は，JupyterHub サーバ上で以下のコマンドを実行し，ログを追跡してください．
journalctl -u jupyterhub -f # jupyterhub の最新ログを継続的に表示
JupyterHub の全ログを確認したい場合は -f オプションを外します．
環境によっては stdout/stderr メッセージが journalctl に表示されないことがあります．その場合は lticontainerspawner.py 内で，self.log.info() または self.log.debug() を使用して，明示的に出力してください．
9.1.2 コンテナ起動時のログ
コンテナ起動時は，start.sh によって各ユーザのホームディレクトリへログが書き込まれます．生成されるログファイルは以下の通りです．
- ~/.ltictr.root.log
- ~/.ltictr.rootless.log
start.sh は起動直後は root 権限で動作し，コンテナの実効環境が整った時点でユーザ権限へ移行します．
.ltictr.root.log は root 権限時のログ，.ltictr.rootless.log はユーザ権限（rootless）移行後のログです．
両方のログが更新されていない場合は，start.sh 実行前にクラッシュした可能性が高いです．この場合は前節 9.1.1 のログが重要な手掛かりになります．
9.1.3 課題提出（Submit）のログ
学生が submit コマンドで課題を提出した場合，~/.submits.log にログが残ります．提出の成否を確認する際に利用できます．
9.2 mod_lticontainer の設定トラブル
9.2.1 mod_lticontainer 操作時に，以下のエラーメッセージが出力されます
The web server process does not have write access to its own home directory. Please check the permissions.
Moodle サーバ上の Web サーバプロセスの実効ユーザ（例：apache）が，自身のホームディレクトリに書き込み権限を持っていない場合に発生します．
対策として，Web サーバプロセスの実効ユーザにホームディレクトリを用意し，書き込み権限を付与してください．「2.3.4 Apache の実効ユーザのホームディレクトリの変更」 を参照してください．
9.2.2 lti_edit 画面が表示されません
JupyterHub の設定が不正な可能性があります．ブラウザバックして，Over View タブ の Edit settings から設定画面を開き，以下を確認してください（4.3.1 参照）．
- JupyterHub (container host) URL
- Container system
- Container user
- Password of container user
9.2.3 lti_edit 画面の Container image に何も表示されません
JupyterHub の設定が不正な可能性があります．Over View タブ の Edit settings を開き，以下を確認してください（4.3.1 参照）．
- JupyterHub (container host) URL
- Container system
- Container user
- Password of container user
9.2.4 lti_edit 画面の Container image に default しか表示されません
Moodle サーバ上で，Web サーバ実効ユーザが 自身のホームディレクトリに書き込み権限を持っていない可能性があります．2.3.4 を参照し，権限を確認してください．
9.2.5 lti_edit 画面で一覧を表示しようとすると，以下のエラーが出ます
podman-remote or podman command does not exist (/usr/bin/podman-remote or /usr/bin/podman). Please install podman-remote package.
通信相手（JupyterHub サーバ）で Podman が動作しているにもかかわらず，Moodle サーバ側に podman-remote がインストールされていないのが原因です．Moodle サーバに podman-remote をインストールしてください（4.4 参照）．
9.2.6 lti_edit 画面で一覧を表示しようとすると，以下のエラーが出ます
docker command does not exist (/usr/bin/docker). Please install docker package.
通信相手（JupyterHub サーバ）で Docker が動作しているにもかかわらず，Moodle サーバ側に Docker CLI（例：docker-ce-cli）がインストールされていないのが原因です．Moodle サーバに CLI をインストールしてください（4.4 参照）．
9.3 コンテナ起動のトラブル
9.3.1 「Start My Server」をクリックすると，即座に「500 Server Internal Error」が発生します
lticontainerspawner.py がクラッシュしている可能性が高いです．9.1.1 JupyterHub のログを確認してください．
（※本文中のファイル名は lticontainerspawner.py に統一しています）
9.3.2 接続用プログレスバーが途中で止まり，その後，赤くなって Timeout します
start.sh の実行中にエラーが発生している可能性が高いです．9.1.2 start.sh のログを確認してください．
9.3.3 Docker の JupyterHub ログで，/usr/local/etc/ のディレクトリ作成失敗エラーが出ます
Unhandled error starting alice's server: ... mkdir /usr/local/etc: read-only file system
Ubuntu では，正式版の Docker の他に Snap 版 Docker が混在している場合があり，その場合に同様の症状が発生することがあります．
以下のコマンドで Snap 版が関係していないか確認してください．
aa-status | grep docker
正常時は docker-default が表示されます．snap に関連する表示が出る場合は，Snap 版が混在している可能性があります．
Snap 版を削除して正式版を利用する例を示します（環境により異なるため，適宜読み替えてください）．
snap remove docker --purge
systemctl unmask docker
systemctl enable --now docker
systemctl reboot # 念のため再起動
9.3.4 JupyterLab の起動に失敗し，/home/others に数字のディレクトリが作成されます
Moodle からユーザ情報（ext_user_username など）が渡っておらず，Moodle の内部ユーザID（数値）がユーザ名として扱われている可能性があります．
外部ツールの設定で「プライバシー」→「ランチャ名をツールと共有する」を確認し，「なし」になっている場合は「常に」に変更してください（5.2.2 参照）．
9.3.5 nss-altfiles 使用時に，すべてのユーザのホームが /home/others に作成されます
使用している nss-altfiles が，バグを含むバージョンである可能性があります．バグのあるバージョンでは，外部 passwd ファイルのパスをコンパイル時に指定できません．
make 実行後に，以下のコマンドで結果を確認してください．
strings libnss_altfiles.so.2 | grep passwd
/etc/passwd のみが表示される場合は，外部 passwd を参照できていません．「5.3.3 代替案：NSS を用いたユーザ情報の共有（altfiles）」 を参照し，nss-altfiles を再コンパイル／再インストールしてください．
9.4 運用時（授業時）のトラブル
9.4.1 頻繁に JupyterLab が落ちます
特に原因が見当たらないのに，不特定多数のユーザで JupyterLab が頻繁に落ちる場合は，メモリ不足の可能性が高いです．
メモリ不足の場合，JupyterLab の左下に メッセージが表示されることがあります（jnotice の機能）．
特定の課題でメモリ不足が発生する場合は，lti_edit で該当課題の Memory Limit を上げてください．
9.4.2 学生が無限ループで巨大なファイルを作ってしまいました
巨大ファイルを開いたまま JupyterLab がクラッシュすると，再接続時に「前回の状態を復元」しようとして巨大ファイルを再読み込みし，メモリエラーで JupyterLab 自体が起動できない場合があります．
この場合は，Web ブラウザの別タブで以下を開いてみてください（末尾に ?reset を付けます）．
https://<JupyterHub サーバ名>[:ポート番号]/user/<ユーザ名>/lab?reset
JupyterLab が起動できたら，Launcher から Terminal を開き，rm などで該当ファイルを削除してください．
それでも復旧できない場合は，サーバ管理者に相談してください．
（※LTI 経由だと URL を直接指定できない環境もあるため，その場合も管理者対応が確実です）
9.4.3 教員ロールのはずなのに，学生の提出物が読めません
旧バージョンで低頻度に発生しました．現バージョンでは修正していますが，発生率が低かったため十分な検証はできていません．
原因は，学生の提出物のグループが TEACHER ではなく root になってしまうことです．
もし現バージョンでも発生した場合は，教師権限を持つユーザ（lti_editor の Teachers に指定されたユーザ）が，提出ディレクトリを表示した状態で Terminal を開き，次を実行してください．（教師権限ユーザは sudo 実行権限を持ちます）
sudo chgrp TEACHER *
9.4.4 datascience-notebook で Pluto が起動できません
Pluto は，学生ごとに 初回のみ 初期化（インストール＋プリコンパイル）が必要です．以下の手順に従ってください．
初期化中は時間とメモリを消費するため，初回だけメモリを増やして実行します．
ただし lti_edit で Memory Limit を上げると，他のユーザにも影響するため，初期化専用の外部ツールを作成するのが合理的です．
また，初期化が完了するまで Pluto を Launcher から起動してはいけません．
- 初回設定用にコンテナメモリを 4GB 程度に設定した 初期化専用外部ツールを用意します
- JupyterLab の Terminal で，該当学生に 一度だけ 次を実行させます（
Pluto readyが表示されれば完了です）
export JULIA_DEPOT_PATH="$HOME/.julia"
export JULIA_NUM_THREADS=1
julia --startup-file=no -e 'import Pkg; Pkg.add("Pluto"); Pkg.precompile(); using Pluto; println("Pluto ready")'
シリーズ「LTI カスタムパラメータによる Moodle＋JupyterHub 連携システムの構築と運用」第９回
第１回に戻る ｜ 前へ：応用（オプション機能，大規模運用，NFS）（構築中！）