---
title: "WSLコンテナ環境 設計書"
---

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

## 1. 概要

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

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

参考資料:

- [1] [Get started with containers on WSL（Microsoft Learn）](https://learn.microsoft.com/en-us/windows/wsl/tutorials/wsl-containers)
- [2] [WSL container（Microsoft Learn）](https://learn.microsoft.com/en-us/windows/wsl/wsl-container)
- [3] [WSL container is now available for public preview（Windows Command Line）](https://devblogs.microsoft.com/commandline/wsl-container-is-now-available-for-public-preview/)
- [4] [Dependencies and Versions（Electrobun）](https://framework.blackboard.sh/electrobun/guides/compatability)
- [5] [Cross-Platform Development（Electrobun）](https://framework.blackboard.sh/electrobun/guides/cross-platform-development)
- [6] [Release 3.0.1（microsoft/WSL）](https://github.com/microsoft/WSL/releases/tag/3.0.1)。WSL container（WSLc）の一般提供を告知するリリース

---

## 3. 構成方式の決定

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

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

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

- 手順を公式ドキュメントで確認できる（[§2](#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 のファイルで正規表現が合致しなくなる事例もある（[開発ノート](/notes/DEVELOPMENT_NOTES) インフラ・設定 19）
- ソースコードをコンテナへ渡す方式は、WSL 側のディレクトリをマウントする方式を第一案とする。`wslc` でのマウントの指定方法は、公式ドキュメントの上記2ページに記載がなく、実機で確認する（[§8](#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. 機密情報とデータ

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

### 4-5. ネットワーク

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

### 4-6. リソース

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

### 4-7. 画面表示

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

---

## 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](#6-2-事前確認項目3の前)）を行う。

| 項目 | 内容 | 完了基準 | 範囲 |
| --- | --- | --- | --- |
| 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 の管理外とし、比較のたびに同じ環境で作り直す（[テスト設計書](/design/common/test-design) ビジュアル回帰テスト）。フォントの描画は OS で変わるため、Windows や macOS で撮った基準画像と Linux の画像は一致しない。Linux 上で撮り直した基準画像と、Linux 上の画像を比較する。

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

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

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

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

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

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

- 対応: Linux の x64 と ARM64。システムレンダラーは WebKitGTK 4.1
- ビルド: 実行中の OS 向けにビルドする。Linux 向けのビルドは Linux 上で `electrobun build --env=stable` を実行する。コンテナ内でのビルドは、この条件に合う
- 実行時の依存: [§4-2](#4-2-containerfile-の方針)のパッケージが必要
- 設定: 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](#4-1-全体方針)） |
| ベースイメージ | Node 24 以上のイメージが `wslc` で取得・起動できること |
| Compose と Docker 互換 API | 報道のとおり使えないかどうか（本書の構成は、いずれも使わずに成立する） |
| Dev Containers 連携 | 一般提供後の `wslc` 対応の手順（[§3-2](#3-2-案bの再検討の条件)） |
| リソース設定 | CPU 数・メモリ・保存先の設定方法と、評価に必要な値 |
| 画面表示 | コンテナから WSLg の画面表示を使えるかどうかと、X11・Wayland のどちらで動くか（[§6-2](#6-2-事前確認項目3の前)）。Electrobun の公式ドキュメントにも記載がない |
| Electrobun の Linux 向け設定 | `build.linux` の最小限の設定、`bundleCEF` の採否、Linux 向けの Bun バイナリの取得（[§6-3](#6-3-項目3の前提確認)） |
| Playwright の起動 | [§6-4](#6-4-既知の注意点)の事象が Linux で起きるかどうか |

---

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

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