ハンズオン実行環境設計概要書¶

1. 背景¶

ハンズオン形式の研修・勉強会を実施する際、参加者のローカル環境差異が大きな障壁となる。とくにDevContainerを基盤とした開発環境は、Docker Desktop、VS Code、WSL2等の事前セットアップが必要であり、Windows・Mac・Linuxの各OSごとに手順が異なる。参加者に事前準備を求めることは、当日のトラブルシューティングに時間を取られるリスクを伴い、ハンズオン本来の学習目的を損なう。

この課題を解消するため、開催側がクラウド上に統一された実行環境を用意し、参加者はブラウザのみでアクセスできる構成を採用する。

2. 目的¶

本環境は以下を実現することを目的とする。

参加者のローカル環境に依存しない、統一されたハンズオン実行環境の提供
参加者の事前準備をゼロにし、ブラウザアクセスのみで作業を開始できる状態の実現
MkDocs等のツールをターミナルから起動し、ブラウザ上でプレビューを確認できるワークフローの提供
Visual Studio Enterpriseサブスクリプションに付帯するAzureクレジット（$150/月）の範囲内での運用

なお、DevContainer自体の操作習得はハンズオンの目的に含まない。DevContainerはあくまで環境構築の手段として開催側が利用し、参加者はその成果物であるコンテナー環境上で作業する。

3. アーキテクチャ¶

3.1 構成概要¶

参加者 (ブラウザのみ)
    │
    │ HTTPS
    ▼
Azure Container Apps (Japan East)
    ┌──────────────────────────────┐
    │  Container Instance (per user)│
    │                              │
    │  ┌────────────┐              │
    │  │ code-server │ ← Ingress   │
    │  │  (port 8080)│   (HTTPS)   │
    │  └────────────┘              │
    │                              │
    │  ┌────────────┐              │
    │  │ mkdocs serve│             │
    │  │  (port 8000)│             │
    │  └────────────┘              │
    │    ↑ 参加者がターミナルから   │
    │      手動起動                │
    │    ↑ code-server内蔵の       │
    │      Simple Browserで閲覧    │
    └──────────────────────────────┘
           │
           │ イメージ取得
           ▼
    Azure Container Registry

3.2 構成要素と役割¶

構成要素	役割
Azure Container Registry	ハンズオン用コンテナイメージの格納
Azure Container Apps Environment	Container Appの実行基盤（参加者全員で共有）
Azure Container Apps (個別)	参加者ごとに1インスタンスをデプロイ。code-serverを稼働させる
code-server	ブラウザ上でVS Code相当のエディター・ターミナルを提供
コンテナイメージ	DevContainerの定義をもとに構築した、ハンズオンに必要なツール・資材を含むイメージ

3.3 ネットワークとアクセス制御¶

各Container Appは外部Ingress（HTTPS）を有効にし、参加者ごとに一意のFQDNを割り当てる
認証はcode-serverのパスワード認証を利用し、参加者ごとに個別のパスワードを環境変数で設定する
mkdocsのプレビュー（port 8000）はコンテナー内部でのみリッスンし、code-server内蔵のSimple Browserを通じて参加者が閲覧する。外部への追加ポート公開は行わない

3.4 コンテナイメージの構成方針¶

コンテナイメージには以下を含める。

code-server（ブラウザ版VS Code）
ハンズオン対象のツール群（MkDocs、関連プラグイン等）
必要なVS Code拡張機能（プリインストール）
ハンズオン資材（ドキュメントソース、設定ファイル等）

イメージのベースには mcr.microsoft.com/devcontainers 系のイメージを利用し、既存のDevContainer定義との整合性を保つ。

3.5 参加者の操作フロー¶

開催側から配布されたURL・パスワードを受け取る
ブラウザでURLにアクセスし、パスワードを入力する
code-serverのエディター・ターミナルが表示される
ターミナルから mkdocs serve 等のコマンドを実行する
code-server内のSimple Browserで localhost:8000 を開き、プレビューを確認する

4. コスト見通し¶

Visual Studio Enterpriseサブスクリプションに付帯するAzureクレジット（$150/月）の範囲内での運用を前提とする。

リソース	概算
Container Apps (1vCPU / 2GBメモリ × 参加者数)	約 $0.06/時間/台
Container Registry (Basic SKU)	$5/月

20名規模・4時間のハンズオンの場合、合計 $10〜15程度を見込む。クレジット上限に対して十分な余裕がある。

5. 運用上の考慮事項¶

5.1 事前準備¶

コンテナイメージのビルドとレジストリへのプッシュは、ハンズオン開催前に完了させておく
参加者分のContainer Appデプロイはスクリプト化し、一括で実行できるようにする
参加者への配布物（URL・パスワードの一覧）を事前に作成する

5.2 当日の運用¶

Container Appsのmin-replicasを1に設定し、スケールインによるコンテナー停止を防止する
参加者がターミナルで誤ってcode-serverプロセスを停止した場合に備え、復旧手順を用意する

5.3 事後の片付け¶

ハンズオン終了後、リソースグループごと削除することで全リソースを一括削除し、課金を停止する

6. 実装に関する注意事項¶

本書に含まれるDockerfile・CLIコマンド等の具体的な実装内容は参考情報である。実際のハンズオン内容・参加者数・ネットワーク要件に応じて、実装の過程で詳細を決定・評価すること。とくに以下の項目は実装段階での検証が必要である。

コンテナーのCPU・メモリサイズの適正値（ハンズオン内容の負荷に依存）
code-serverのバージョンおよびVS Code拡張機能の互換性
Simple Browserによるmkdocsプレビューの表示品質と制約
参加者が同時アクセスした際のContainer Apps Environmentの性能
パスワード認証の強度が研修用途として十分かの判断

7. 実装・設計メモ¶

開発環境情報
- settings.local.json

ハンズオン実行環境 設計概要書¶