holoscan-install-container

Holoscan NGC コンテナーのインストール

目的

NGC（nvcr.io/nvidia/clara-holoscan/holoscan）から公式 Holoscan SDK コンテナーをプルして検証します。ホスト GPU に適した CUDA／アーキテクチャタグを選択し、同梱の Python および C++ サンプルで動作を確認します。

前提条件

• NVIDIA GPU と正常に動作するドライバー（nvidia-smi）を備えた Linux ホスト。
• Docker がインストールされており、ユーザーが docker グループに属していること（または sudo を使用できること）。
• NVIDIA Container Toolkit がインストールされていること（docker run --gpus all が動作すること）。
• イメージのプル用に約 10～20 GB の空きディスク容量。
• nvcr.io および docs.nvidia.com へのネットワークアクセス。

制限事項

• コンテナーイメージは以下のタグ一覧のみを対象としており、内部に Conda／pip 環境はありません。
• GUI サンプルには X11 転送が必要です。このスキルではそれを避けるため、Holoviz をヘッドレスで実行します。
• タグのサフィックスはホスト GPU／ドライバーと一致する必要があります（cuda13 / cuda12-dgpu / cuda12-igpu）。サフィックスが間違っていると、CUDA の初期化に失敗します。

手順

• コンテナーリポジトリ：nvcr.io/nvidia/clara-holoscan/holoscan。
• https://docs.nvidia.com/holoscan/sdk-user-guide/sdk_installation.html のドキュメントページが正本です。以下の内容と食い違う場合は、このページを取得してください。
• 以下の手順を順番に進めます。タグを選択し、GPU パススルーとプルを確認した後、6 つのサンプルで検証し、最後に起動コマンドを案内します。

ステップ 1：タグを選択する

タグは <version>-<suffix> です（例：v4.1.0-cuda13）。現在の SDK バージョンは上記のドキュメントページで確認し、サフィックスは nvidia-smi の「CUDA Version」フィールド（表のヘッダー右上）から選択します。

nvidia-smi の CUDA Version	サフィックス
13.x 以上	cuda13
12.x、Ampere／Ada dGPU	cuda12-dgpu
12.x、ARM64 iGPU（nvgpu）	cuda12-igpu

コンテナーにホストドライバーがサポートするより新しい CUDA マイナーバージョンが含まれている場合、「CUDA Forward Compatibility mode ENABLED」のバナーが表示されるのは想定どおりであり、エラーではありません。Forward-compat シムにより、同じメジャーバージョンの範囲内で、コンテナーの CUDA ランタイムを古いホストドライバー上で動作させられます。

ステップ 2：GPU パススルーを確認してからプルする

docker run --rm --gpus all ubuntu:22.04 nvidia-smi 2>&1 | tail -5

Docker が見つからない場合は、https://docs.docker.com/engine/install/ からインストールしてください。GPU パススルーに失敗する場合は、https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html に従って NVIDIA Container Toolkit をインストールし、再試行してください。

プルします（約 10～20 GB。開始前にユーザーに警告してください）。

docker pull nvcr.io/nvidia/clara-holoscan/holoscan:<TAG>

ステップ 3：6 つのサンプルで検証する

テスト対象：基本的な Python バインディング（1a）、基本的な C++ ランタイム（1b、2a）、Python + Holoviz／Vulkan（2b、3a）、C++ + Holoviz／Vulkan（3b）。Holoviz のサンプルは常にヘッドレスで実行します（YAML に headless: true を挿入します）。これはディスプレイが接続されているかどうかにかかわらず動作し、SSH 経由での GUI の障害も回避できます。

IMG=nvcr.io/nvidia/clara-holoscan/holoscan:<TAG>
RUN=(docker run --rm --runtime=nvidia --gpus all --cap-add CAP_SYS_PTRACE --ipc=host --ulimit memlock=-1 --ulimit stack=67108864)

# 1a. hello_world (Python) — expect "Hello World!"
"${RUN[@]}" "$IMG" bash -c \
  "ulimit -s 32768 && python3 /opt/nvidia/holoscan/examples/hello_world/python/hello_world.py"

# 1b. hello_world (C++) — expect "Hello World!"
"${RUN[@]}" "$IMG" bash -c \
  "ulimit -s 32768 && /opt/nvidia/holoscan/examples/hello_world/cpp/hello_world"

# 2a. tensor_interop (C++) — expect tensors doubling each pass, "Graph execution finished."
"${RUN[@]}" "$IMG" bash -c \
  "ulimit -s 32768 && /opt/nvidia/holoscan/examples/tensor_interop/cpp/tensor_interop"

# 2b. tensor_interop (Python, 10 frames) — Holoviz, headless. The YAML has no
#     headless field by default, so inject one under `holoviz:`. Expect
#     "message received (count: 10)".
"${RUN[@]}" "$IMG" bash -c "
  ulimit -s 32768
  sed -e 's/count: 0/count: 10/' \
      -e 's/repeat: true/repeat: false/' \
      -e 's/realtime: true/realtime: false/' \
      -e 's/^holoviz:/holoviz:\n  headless: true/' \
      /opt/nvidia/holoscan/examples/tensor_interop/python/tensor_interop.yaml > /tmp/ti.yaml
  cd /opt/nvidia/holoscan/examples/tensor_interop/python
  python3 tensor_interop.py --config /tmp/ti.yaml
"

# 3a. video_replayer (Python, 10 frames) — Holoviz, headless. Inject `headless: true`
#     under `holoviz:` (above `width: 854`). Same sed works for the C++ YAML in 3b —
#     both files share the same `holoviz:` section shape.
"${RUN[@]}" "$IMG" bash -c "
  ulimit -s 32768
  sed -e 's/count: 0/count: 10/' \
      -e 's/repeat: true/repeat: false/' \
      -e 's/realtime: true/realtime: false/' \
      -e 's/^  width: 854/  headless: true\n  width: 854/' \
      /opt/nvidia/holoscan/examples/video_replayer/python/video_replayer.yaml > /tmp/vr.yaml
  cd /opt/nvidia/holoscan/examples/video_replayer/python
  HOLOSCAN_INPUT_PATH=/opt/nvidia/holoscan/data python3 video_replayer.py --config /tmp/vr.yaml
"

# 3b. video_replayer (C++, 10 frames) — same headless injection as 3a. The C++
#     YAML hard-codes `directory: "../data/racerx"`, but HOLOSCAN_INPUT_PATH
#     overrides it, so we don't need to patch that field.
"${RUN[@]}" "$IMG" bash -c "
  ulimit -s 32768
  sed -e 's/count: 0/count: 10/' \
      -e 's/repeat: true/repeat: false/' \
      -e 's/realtime: true/realtime: false/' \
      -e 's/^  width: 854/  headless: true\n  width: 854/' \
      /opt/nvidia/holoscan/examples/video_replayer/cpp/video_replayer.yaml > /tmp/vr_cpp.yaml
  cd /opt/nvidia/holoscan/examples/video_replayer/cpp
  HOLOSCAN_INPUT_PATH=/opt/nvidia/holoscan/data ./video_replayer --config /tmp/vr_cpp.yaml
"

ステップ 4：起動コマンド

• https://catalog.ngc.nvidia.com/orgs/nvidia/teams/clara-holoscan/containers/holoscan を確認します。
• 以下の Docker フラグについてユーザーに説明します。
• 追加のフラグ（V4L2 ビデオデバイスのマウント方法など）については、そのリンクを参照するようユーザーに案内します。

docker run -it --rm \
  --runtime=nvidia --gpus all --cap-add CAP_SYS_PTRACE \
  --ipc=host --ulimit memlock=-1 --ulimit stack=67108864 \
  nvcr.io/nvidia/clara-holoscan/holoscan:<TAG>
# Examples: /opt/nvidia/holoscan/examples/
# Mount files: -v /host/path:/container/path
# GUI examples: add -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=$DISPLAY

次の手順：

• 確認する：ls /opt/nvidia/holoscan/examples/
• 1 つのサンプルを詳しく見る：/holoscan-explain-example

トラブルシューティング

• docker: Error response from daemon: could not select device driver "nvidia"。 NVIDIA Container Toolkit がないか、正しく設定されていません。ステップ 2 のリンクに従ってインストールし、Docker を再起動してください。
• コンテナー内で CUDA の初期化に失敗する。 タグのサフィックスがホストと一致していません。nvidia-smi の CUDA Version とステップ 1 の表を再確認してください。
• サンプルの起動時にセグメンテーションフォールトが発生する。 コンテナー内で ulimit -s 32768 が適用されていません。ステップ 3 に示す bash -c "ulimit -s 32768 && ..." のパターンを使用してください。
• Holoviz のサンプルが停止する／SSH 経由でウィンドウが表示されない。 YAML に headless: true が設定されていません。ステップ 3 に示す sed による挿入を使用してください。
• video_replayer がデータを見つけられない。 HOLOSCAN_INPUT_PATH=/opt/nvidia/holoscan/data を設定してください。これにより YAML にハードコードされたパスが上書きされます。