コンテンツにスキップ
Documents for MorningStatusApp
Esc
↑↓移動↵開く⌘Jプレビュー
このページの内容

WSLコンテナ環境 設計書

最終更新: 2026-10-28（新規作成、#207）

1. 概要

Windows に組み込まれた Linux コンテナの実行機能（WSL container）で MorningStatusApp の Linux 環境を構築し、その利用価値を評価するための設計書。親Issueは MorningStatusApp#1698、環境の構築と評価の実施は MorningStatusApp#1743 で行う。

  • 目的: WSL container の利用価値の評価。MorningStatusApp 自体を Linux へ対応させること（Linux 向けの配布）は目的に含まれない
  • 想定: Linux サポートの検討は、デスクトップアプリ（デスクトップモード）の Linux 対応を想定している。評価項目3〜5（ビルド・起動・操作性）が、この想定に対応する
  • 論点: Windows 上の WSL container で Ubuntu などの Linux 環境を動かし、その中でデスクトップモードを実行する環境となるか。環境としての利用価値は項目1・2（品質チェック・スクリーンショット比較）で判定し、デスクトップモードの実行可否は項目3〜5の結果で Linux サポートの起票要否に反映する（§7-2）
  • 位置づけ: 採用するが、継続するかは評価の結果で決める。環境の定義ファイルと本書はリポジトリに残し、いつでも再開できる状態にする
  • 評価の結果: Linux サポートが必要と判定した場合は、別Issueとして起票する（判定基準は§7-2）

1-1. 用語

用語 意味
WSL container WSL に組み込まれた Linux コンテナの実行機能。CLI の wslc.exe と、Windows アプリ向けの API からなる
wslc WSL container の CLI。wslc.exe の略記
WSL 3.0 WSL container が一般提供された WSL 3.0.1（2026-09-29 公開、[6]）の呼称。公式の機能名は WSL container で、本書では WSL container と表記する
WSLg WSL 上の Linux アプリの画面を Windows に表示する仕組み

2. 前提

公式ドキュメントで確認した内容と、報道のみで確認した内容を区別して記載する。

項目 内容 確認状況
WSL のバージョン 2.9.3 以上が必要。wsl --version で確認し、wsl --update で更新する 公式ドキュメントで確認（[1]、[2]）
wslc の導入 wslc.exe は WSL に組み込まれており、別のエンジンのインストールは不要 公式ドキュメントで確認（[1]）
イメージのビルド Containerfile を置き、wslc build -t <名前> . でビルドする。チュートリアルの例は FROM・RUN・COPY を使う通常の Dockerfile 構文 公式ドキュメントで確認（[1]）
イメージの取得 docker.io などのレジストリから取得する（API のサンプルは docker.io/library/alpine:latest） 公式ドキュメントで確認（[2]）
ポートの公開 wslc run -p <ホスト側>:<コンテナ側> で公開し、Windows のブラウザから localhost で参照する 公式ドキュメントで確認（[1]）
ソースコードの置き場所 Windows 側のファイルシステムではなく、WSL 側のファイルシステムに置く。Windows 側に置くとファイルアクセスが大幅に遅くなる 公式ドキュメントで確認（[1]）
Electrobun の Linux 対応 Linux の x64 と ARM64 に対応し、システムレンダラーは WebKitGTK 4.1。ビルドは実行中の OS 向けに行い、Linux 向けは Linux 上で実行する 公式ドキュメントで確認（[4]、[5]）
画面表示（WSLg、X11、Wayland） WSL container と Electrobun のいずれの公式ドキュメントにも、コンテナから WSLg を使う方法の記載がない 公式ドキュメントに記載なし（実機で未確認）
Compose 公式ドキュメントの上記2ページに記載がない。報道では未対応とされている 報道のみ（実機で未確認）
Docker Engine 互換 API 公式ドキュメントの上記2ページに記載がない。報道では、docker コマンドや DOCKER_HOST 経由のツールは使えないとされている 報道のみ（実機で未確認）
VS Code Dev Containers との連携 2026-06-29 のプレビュー期間の告知記事では、Dev Containers 拡張の pre-release 版で、設定の「Docker Path」を wslc にして使う。一般提供（WSL 3.0.1、[6]）後の現状は確認できていない 告知記事のみ（[3]、一般提供後は未確認）

参考資料:

3. 構成方式の決定

環境の構成方式は、次の3案を比較して決める。

案 内容 評価
A wslc を直接使い、Containerfile でイメージを定義する 採用
B VS Code の Dev Containers 経由で wslc を使う 採用を見送り、再検討の条件を§3-2に定める
C Docker 互換の環境（Docker Desktop など）を使う 対象外

3-1. 案Aを採用する理由

  • 手順を公式ドキュメントで確認できる（§2）。評価の対象は WSL 標準のコンテナ機能そのものであり、追加のツールを挟まずに評価できる
  • 必要な構成は、開発ツール一式を入れた単一のコンテナである。複数コンテナの連携（Compose）は要件に含まれない
  • 環境の定義が Containerfile 1つに収まり、撤去と再開の手順が単純になる

3-2. 案Bの再検討の条件

Dev Containers 拡張の wslc 対応が一般提供になり、公式ドキュメントで手順を確認できた時点で、案Bの採否を再検討する。再検討の結果は、本書の改訂として記録する。

3-3. 案Cを対象外とする理由

評価の目的が、WSL 標準のコンテナ機能の利用価値を見ることにある。Docker 互換の環境を使うと、その価値を評価できない。

4. 環境の構成

4-1. 全体方針

  • 単一のコンテナに、品質チェック・スクリーンショット比較・Electrobun のビルドと起動に必要なツールを入れる
  • ソースコードは、WSL 側のファイルシステムに clone する。Windows 側で clone した作業ツリーは、core.autocrlf=true により改行コードが CRLF になり、Linux 上のシェルスクリプトが動かなくなるおそれがある。CRLF のファイルで正規表現が合致しなくなる事例もある（開発ノート インフラ・設定 19）
  • ソースコードをコンテナへ渡す方式は、WSL 側のディレクトリをマウントする方式を第一案とする。wslc でのマウントの指定方法は、公式ドキュメントの上記2ページに記載がなく、実機で確認する（§8）。マウントできない場合は、コンテナ内で clone する

4-2. Containerfile の方針

項目 方針
ベース Node 24 以上の Linux イメージ。MorningStatusApp の package.json が Node 24 以上を要求している
パッケージマネージャ Bun をインストールする
ブラウザ Playwright のブラウザと依存ライブラリをインストールする
Playwright のバージョン 本体の playwright と @playwright/test のバージョンに合わせる。ずれると、インストール済みのブラウザと合わなくなるおそれがある（開発ノート テスト手法 51）
Electrobun の実行時の依存 GTK 3・WebKitGTK 4.1・Ayatana AppIndicator・librsvg のパッケージをインストールする。Ubuntu・Debian 系のパッケージ名は libgtk-3-0・libwebkit2gtk-4.1-0・libayatana-appindicator3-1・librsvg2-2。CEF を同梱する場合も必要（[4]、[5]）
イメージのタグ 実装時に確定し、Containerfile に記録する

4-3. 初期化手順（コンテナ内）

ソースコードを用意したあと、次の順に実行する。prisma generate は DB への接続を必要としない。

  1. bun install
  2. bunx prisma generate
  3. bunx panda codegen

panda codegen で生成する styled-system は Git の管理外であり、未生成だとテストと型チェックが失敗する。

4-4. 機密情報とデータ

  • 機密値は、イメージにもリポジトリにも含めず、コンテナの実行時に環境変数として渡す
  • 必要な環境変数は、環境変数一覧を参照する
  • スクリーンショット比較は、表示データを Vercel Blob と Neon から取得する（テスト設計書 ビジュアル回帰テスト）。コンテナに渡す変数の範囲は、実機で確認して確定する

4-5. ネットワーク

  • 開発サーバーのポートは -p で公開し、Windows のブラウザから localhost で参照する
  • Playwright はコンテナ内から、同じコンテナ内の開発サーバーを参照する

4-6. リソース

CPU 数・メモリ・保存先は、wslc の設定（WSL container settings）で変更できる。既定値で開始し、不足した場合に調整する。調整した値は、評価結果の記録欄（§7-1）に残す。

4-7. 画面表示

デスクトップモードの起動と操作には、ディスプレイセッションが必要である（[5]）。コンテナから WSLg の画面表示を使えるかは、WSL container と Electrobun のいずれの公式ドキュメントにも記載がない。画面を表示できるかは、項目3の前の事前確認（§6-2）で確かめる。

5. 起動・再開・撤去

コマンドは公式のチュートリアル（[1]）に記載されたものに限る。

手順 コマンド 備考
バージョンの確認 wsl --version 2.9.3 以上であること
WSL の更新 wsl --update 2.9.3 未満の場合
動作の確認 wslc version、wslc run --rm hello-world 初回のみ
イメージのビルド wslc build -t <名前> . Containerfile のあるディレクトリで実行する
起動 wslc run -d --name <名前> -p <ホスト側>:<コンテナ側> <イメージ>
コンテナ内でのコマンド実行 wslc exec <名前> <コマンド> 品質チェックなどを実行する
状態の確認 wslc container list、wslc container logs <名前>
停止 wslc container stop <名前>
再開 同じイメージから起動をやり直す イメージが残っていれば、ビルドは不要。wslc image list で確認する
コンテナの撤去 wslc container prune 停止したコンテナをすべて削除する
イメージの撤去 wslc image prune 使われていないイメージを削除する

6. 評価項目と完了基準

評価項目は次の5つ。実装Issue（#1743）の範囲は、環境の構築と項目1〜4とし、項目5は項目4の結果を見て必要な場合に追加する。項目3の前に、画面表示の事前確認（§6-2）を行う。

項目 内容 完了基準 範囲
1 品質チェックが Linux 上で通るか bun run test・bun run lint（警告 0 件）・bun run type-check がすべて成功する #1743
2 スクリーンショット比較が Linux 上で動くか bun run test:visual で、Linux 上に基準画像を作成し、同じ環境で比較を最後まで実行できる #1743
3 Linux 向けビルド（Electrobun）が通るか ビルドが最後まで成功し、成果物ができる #1743
4 項目3の成果物が起動するか 成果物が起動し、画面が表示される。コンテナ内で画面を表示できない場合は、通常の Ubuntu（WSL）での起動を代替確認とし、その結果を記録する。代替確認は WSL container の評価には含めない #1743
5 起動したアプリの操作性に問題がないか 主要な画面の操作ができる。項目4を代替確認で行った場合は、同じ環境で確認する 項目4の結果を見て追加

6-1. 項目2の基準画像

基準画像は Git の管理外とし、比較のたびに同じ環境で作り直す（テスト設計書 ビジュアル回帰テスト）。フォントの描画は OS で変わるため、Windows や macOS で撮った基準画像と Linux の画像は一致しない。Linux 上で撮り直した基準画像と、Linux 上の画像を比較する。

6-2. 事前確認（項目3の前）

デスクトップモードの評価は、コンテナ内から画面を表示できるかに左右される。項目3の着手前に、画面を表示するだけの小さな GUI アプリをコンテナ内で起動し、Windows 上に画面が表示されるかを確認する。使用するアプリの選定は #1743 で行う。

結果 次の動き
画面が表示される 項目3・4を、コンテナ内で続ける
画面が表示されない 項目3（ビルド）までをコンテナ内で行う。項目4は、通常の Ubuntu（WSL）での起動を代替確認とする

結果は、評価結果の記録欄（§7-1）に残す。

6-3. 項目3の前提確認

Electrobun の Linux 対応は、公式ドキュメントで確認した（[4]、[5]）。

  • 対応: Linux の x64 と ARM64。システムレンダラーは WebKitGTK 4.1
  • ビルド: 実行中の OS 向けにビルドする。Linux 向けのビルドは Linux 上で electrobun build --env=stable を実行する。コンテナ内でのビルドは、この条件に合う
  • 実行時の依存: §4-2のパッケージが必要
  • 設定: MorningStatusApp のデスクトップアプリの定義（Electrobun の設定）には、現時点で macOS 向けと Windows 向けの項目だけがあり、Linux 向けの項目がない。公式ドキュメントには、build.linux に icon を指定する例がある

設定とバイナリについて、次のとおり扱う。

  • ビルドに必要な最小限の Linux 向け設定の追加は、#1743 の範囲に含める。配布形式など、Linux サポートとしての設定の整備は、Linux サポートの起票に含める
  • bundleCEF（CEF の同梱）の採否は、実機での確認結果を見て決める。WebKitGTK 4.1 と CEF のどちらを使うかで、画面表示の結果が変わる可能性がある
  • Electrobun に同梱される Bun のバイナリは、プラットフォームごとに固定されたバージョンで、ビルド時に取得される（開発ノート インフラ・設定 25）。Linux 向けのバイナリが取得できるかも、実機で確認する

6-4. 既知の注意点

注意点 内容
開発サーバーの起動 脆弱性のある Next.js の next dev は、起動時に通知を出して終了コード 1 で止まることがあり、bun run test:visual が全件失敗する。その場合は開発サーバーを先に起動して再利用させる（開発ノート テスト手法 61）
Playwright の起動 Windows と Bun の組み合わせでは、Playwright のブラウザ起動が応答しなくなる事例がある（開発ノート テスト手法 24）。Linux で同じ事象が起きるかを観察し、起きた場合は記録欄に残す
レンダラーの混在 1つの Linux プロセスは、CEF と WebKitGTK のどちらか一方のレンダラーを使う（[5]）

7. 評価結果の記録と判定

7-1. 記録欄

評価を実施した時点で、結果を次の表に記入する。

項目 結果 実施日 環境（WSL・wslc のバージョン、イメージ） 備考（失敗時の要因、調整したリソース）
事前確認（画面表示） 未実施 - - -
1. 品質チェック 未実施 - - -
2. スクリーンショット比較 未実施 - - -
3. Linux 向けビルド 未実施 - - -
4. 成果物の起動 未実施 - - -
5. 操作性 未実施 - - -

結果の欄には、合格・不合格・未実施のいずれかを記入する。項目4を通常の Ubuntu（WSL）での代替確認で行った場合は、「代替確認で合格」または「代替確認で不合格」を記入し、備考にその旨を記入する。

7-2. 判定基準

環境としての利用価値は、項目1・2の結果で判定する。

判定 条件 次の動き
利用価値あり 項目1・2が合格 Linux サポートの起票要否を、下表の項目3・4の結果で決める
要再実施 項目1または項目2が不合格で、環境側の調整（リソースの変更など）で回避できる可能性がある 調整内容を備考に記入して再実施する。回避できないと判断した時点で「利用価値なし」とする
利用価値なし 項目1または項目2が不合格で、環境側の要因により回避できない 起票しない。継続しない旨を記録する

「利用価値あり」の場合、Linux サポートの起票要否は、項目3・4の結果で決める。

項目3・4の結果 Linux サポートの起票
項目3が合格、項目4が合格または代替確認で合格 起票する。項目5を実施した場合は、不合格の内容を起票する Issue に含める
項目3または項目4が不合格 起票しない。要因を記録する

代替確認の結果は、利用価値の判定には使わず、起票の判断にだけ使う。

判定は、評価結果の記録欄を記入した時点で、Issue（#1743）に記録する。判定が「利用価値なし」でも、環境の定義ファイルと本書は残す。

8. 実機で未確認の事項

macOS 上では wslc を実行できないため、次の事項は Windows の実機での確認が必要である。確認は #1743 で行い、結果は本書に反映する。

事項 確認する内容
マウントの指定 wslc で WSL 側のディレクトリをコンテナへマウントする指定方法（§4-1）
ベースイメージ Node 24 以上のイメージが wslc で取得・起動できること
Compose と Docker 互換 API 報道のとおり使えないかどうか（本書の構成は、いずれも使わずに成立する）
Dev Containers 連携 一般提供後の wslc 対応の手順（§3-2）
リソース設定 CPU 数・メモリ・保存先の設定方法と、評価に必要な値
画面表示 コンテナから WSLg の画面表示を使えるかどうかと、X11・Wayland のどちらで動くか（§6-2）。Electrobun の公式ドキュメントにも記載がない
Electrobun の Linux 向け設定 build.linux の最小限の設定、bundleCEF の採否、Linux 向けの Bun バイナリの取得（§6-3）
Playwright の起動 §6-4の事象が Linux で起きるかどうか

改訂履歴（バージョン降順に記載）

版 更新日 変更内容
1.0 2026-10-28 新規作成（#207）

このページは役に立ちましたか？