マシンセットアップ

これらの手順は、Porta On Prem の実行を予定している各マシンの初期セットアップ用です。

ノート

Windows Subsystem for Linux と、Windows の cmd、PowerShell、または Terminal を使用して Docker を操作します。

WSL Setup and Ubuntu Installation

1. インターネットにアクセスできるデバイスで、次をダウンロードします。

   • WSL Kernel Update 5.10.102.2 for x64 arch
   • WSL 2 version 2.0.14 x64 arch
   • Porta Ubuntu 22.04 WSL2 image
   • Stock Ubuntu 22.04 WSL2 image（念のため）
   • Docker Desktop 4.28.0

2. ダウンロードしたファイルを、インストールするマシンにコピーします。

3. マシンに保留中の Windows 更新プログラムがすべてインストールされていることを確認します。

4. Windows のスタートメニューを開き、Windows Features を検索して、Turn Windows features on or off を選択します。

5. 次の機能がまだチェックされていない場合は、有効にします。

   • Virtual Machine Platform
   • Windows Subsystem for Linux

6. これらの機能を有効にした後、マシンを再起動します。

7. ダウンロードしてマシンに転送したファイルの中で、wsl_update_x64_XXXXXX.cab をダブルクリックして WSL2 カーネルの .msi ファイルを抽出します。

8. wsl_update_x64.msi を実行して、WSL2 カーネル更新プログラムをインストールします。

   • お使いのマシンがすでに 5.10 より新しい場合、このステップは機能しないことがあります。次のステップに進んでください。

9. PowerShell を管理者として開きます。

10. PowerShell で dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart を実行します。

11. PowerShell で dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart を実行します。

12. wsl.2.0.14.0.x64.msi をダブルクリックして、WSL をバージョン 2.0.14 に更新します。

    • お使いのマシンがすでに 2.0.15 より新しい場合、このステップは機能しないことがあります。次のステップに進んでください。

13. マシンを再起動します。

14. PowerShell を管理者として開きます。

15. wsl --set-default-version 2 を実行します。

16. wsl --version（または wsl --status）で WSL のバージョンを確認します。

    • WSL バージョンは 2.0.14 以上である必要があります。
    • カーネルバージョンは 5.10.102.2 以上である必要があります。

    ノート

    wsl コマンドの実行で次のエラーが表示される場合:

    This application requires the Windows Subsystem for Linux Optional Component.
    Install it by running: wsl.exe --install --no-distribution
    The system may need to be restarted so the changes can take effect.
    Error code: Wsl/WSL_E_WSL_OPTIONAL_COMPONENT_REQUIRED

    続行する前にインストールが必要な、保留中の Windows 更新プログラムがある可能性があります。

17. Porta Ubuntu イメージをインストールします。

    1. wsl --shutdown を実行します。
    2. wsl --import Ubuntu-20.04 Ubuntu %USERPROFILE%\Downloads\Ubuntu2204-WSLimage.tar を実行します。
       • 必要に応じて、%USERPROFILE%\Downloads\Ubuntu2204-WSLimage.tar を、ダウンロードした Ubuntu WSL イメージへのパスに置き換えます。
    3. インポートの完了には数分かかることがあります。
    4. 最初の WSL Ubuntu ログインは root ユーザーで行われます。設定ファイルを作成して更新し、デフォルトユーザーを設定する必要があります。
    5. PowerShell で wsl を実行して、WSL コマンドラインインターフェイスを開きます。
    6. 次を実行します。

       touch /etc/wsl.conf

       echo -e "[user] \n default=px" > /etc/wsl.conf

       ノート

       ファイル /etc/wsl.conf に余分な文字があると、このユーザーは使用されません。cat /etc/wsl.conf を実行してファイルを確認してください。次のように表示されるはずです。

       [user]
       default=px

    7. exit を実行し、PowerShell で wsl --terminate Ubuntu-20.04 を実行します。
    8. 再び WSL を開くと、px ユーザーとして開かれるはずです。

    Porta イメージの使用に問題がある場合は、下記の Stock WSL Ubuntu Image Installation セクションを参照し、stock イメージのインストール後にここに戻って次の手順を実行してください。

18. ディストロのインストールが完了したら、PowerShell で wsl -l -v --all を実行すると Ubuntu-22.04 が一覧表示されるはずです。

    • Ubuntu-22.04 が表示されない場合は、WSL を起動して使用中のディストロを確認し、PowerShell で wsl を実行してから cat /etc/os-release を実行して OS バージョンを確認してみてください。出力は次のようになるはずです。

      PRETTY_NAME="Ubuntu 22.04.4 LTS"
      NAME="Ubuntu"
      VERSION_ID="22.04"
      VERSION="22.04.4 LTS (Jammy Jellyfish)"
      VERSION_CODENAME=jammy
      ID=ubuntu
      ID_LIKE=debian
      HOME_URL="https://www.ubuntu.com/"
      SUPPORT_URL="https://help.ubuntu.com/"
      BUG_REPORT_URL="https://bugs.launchpad.net/ubuntu/"
      PRIVACY_POLICY_URL="https://www.ubuntu.com/legal/terms-and-policies/privacy-policy"
      UBUNTU_CODENAME=jammy

19. マシンを再起動します。

20. PowerShell を管理者として再度開きます。

21. インストールを再確認します。wsl --status を実行すると、次が表示されるはずです。

    • Default Distribution: Ubuntu-22.04
    • Default Version: 2
    • 「WSL2 is not supported with your current machine configuration」と表示される場合は、BIOS で仮想化を有効にする必要があります。このプロセスはマシンによって異なります。

22. wsl -l -v --all を実行して Ubuntu が WSL2 を使用していることを確認します。次のようになるはずです。

    NAME                   STATE           VERSION
    * Ubuntu-22.04           Running         2

23. PowerShell で次のコマンドを実行して、Ubuntu がデフォルトのディストロとして使用されていることを確認します。

    • wslconfig /s Ubuntu-22.04

24. wsl --status を再度実行するか、wslconfig /l を実行して確認できます。

25. これで Docker のインストール に進めます。

詳細については、Official Microsoft WSL manual install instructions を参照してください。

Stock WSL Ubuntu Image Installation

1. Ubuntu AppxBundle の拡張子を .AppxBundle から .zip にリネームします。
2. この zip アーカイブを展開します。
3. 展開したフォルダ内で、名前が _x64.appx で終わるファイル（おそらく Ubuntu_2204.1.7.0_x64.appx）を次のステップで使用します。
4. PowerShell を管理者として開き、.appx を含むフォルダに移動して、そのディレクトリで次のコマンドを実行します。app-name は Linux ディストリビューションの .appx ファイルの名前です: Add-AppxPackage .\Ubuntu_2204.1.7.0_x64.appx
5. Appx パッケージが完了したら、次の手順を実行 して新しいディストリビューションの実行を開始できます（wsl -l コマンドは、このステップが完了するまでディストリビューションがインストールされていることを表示しません）。
   1. PowerShell を使用して、Linux ディストリビューションのパスを Windows 環境の PATH に追加します（この例では C:\Users\Administrator\Ubuntu）。

      $userenv = [System.Environment]::GetEnvironmentVariable("Path", "User")
      [System.Environment]::SetEnvironmentVariable("PATH", $userenv + ";C:\Users\Administrator\Ubuntu", "User")

   2. PowerShell で ubuntu2204.exe を実行します。これにより Ubuntu 22.04 ディストロのインストールが開始され、ユーザーセットアップのプロンプトが表示されます。
   3. ユーザー名とパスワードの入力を求められたら、新しいユーザー名とパスワードを入力します（このユーザーは sudo、つまり管理者権限を持ちます）。
      • ユーザー名には小文字、アンダースコア、ダッシュのみを使用する必要があります。
      • root ユーザーで進めないでください。これはセキュリティリスクであり、インストールに問題を引き起こします。

      ノート

      PATH への追加は不要な場合があります。exe は %LOCALAPPDATA%\Microsoft\WindowsApps の CanonicalGroupLimited.Ubuntu22.04LTS... のようなフォルダにあるはずで、ubuntu2204.exe をクリックするか、PowerShell からフルパスを呼び出すだけで Ubuntu のインストールを開始できます。

6. 上記の WSL Setup and Ubuntu Installation セクションの ステップ 18 から手順を再開します。

.wslconfig による WSL リソース使用量の制限

ヒント

WSL 構成ファイルは Windows の %USERPROFILE%\.wslconfig にあります。

ファイルがまだ存在しない場合は、Notepad などのテキストエディタで作成できます。

1. Notepad で .wslconfig ファイルを開くか作成する

WSL のリソース使用量を制限するには、.wslconfig ファイルを開くか作成します。ファイルが [wsl2] で始まることを確認し、続く行でメモリやプロセッサなどのいくつかのプロパティを定義できます。

このサンプルファイルは、PX に適したデフォルト構成です。

[wsl2]
# Limits VM memory in WSL to no more than xGB
memory=32GB

# Makes the WSL VM use x virtual processors
processors=6

# Turn off gui support. Can offer better performance
guiApplications=false

# NOT RECOMMENDED -- Limits the maximum size in bytes that a distro filesystem is allowed to take up
# 161061273600 -> 150GB
# defaultVhdSize=161061273600

2. 変更を保存する

構成を入力したら、ファイルを保存して閉じます。

注意

保存する際は、次を必ず確認してください。

• ファイル名 .wslconfig の先頭の . が欠けていないこと。
  • ❌ wslconfig
  • ✅ .wslconfig
• ファイルに拡張子が追加されていないこと。
  • 保存する際、「ファイルの種類」の選択で「すべてのファイル (*.*)」を選択します。
    • ❌ .wslconfig.txt
    • ✅ .wslconfig

3. Docker Desktop と WSL をシャットダウンする

1. システムトレイを使用して Docker Desktop を終了します。
2. PowerShell を開きます。
3. wsl --shutdown を実行して WSL を停止します。
4. wsl -l -v を実行して、ディストリビューションがすべて「Stopped」と表示されることを確認します。

4. Docker Desktop を再度起動する

Docker Desktop を再度起動します。WSL は新しい構成で読み込まれるはずです。

---

Docker

Windows 用 Docker Desktop バージョン 4.28.0 をダウンロードしてインストールします。

• https://desktop.docker.com/win/main/amd64/139021/Docker%20Desktop%20Installer.exe

WSL2 バックエンド用のインストーラーの指示に従い、Docker でプロンプトが表示されたら、Configuration ページの Use WSL 2 instead of Hyper-V オプションが選択されていることを確認します。

インストールが完了したら、Docker Desktop を開いて実行されていることを確認し、次の手順に進みます。

1. ログイン時に Docker Desktop を起動するように設定します。

   • 右上のメニューバーで、歯車アイコンをクリックして設定を開きます。
   • 左サイドバーの「General」タブを選択して、General 設定を表示します。
   • 「Start Docker Desktop when you log in」のボックスをオンにします。
   • また、次のチェックを外します。
     • Send usage statistics
     • Show CLI Hints
     • SBOM Indexing
   • 右下の「Apply & Restart」をクリックします。
   • 右上の内側の「X」アイコンを使用して、Settings メニューを閉じます。

2. Docker Desktop の設定で Resource Saver を無効にします。

   • 右上のメニューバーで、歯車アイコンをクリックして設定を開きます。
   • 左サイドバーの「Resources」タブを選択します。
   • 「Enable Resource Saver」のボックスの チェックを外します。
   • 右下の「Apply & Restart」をクリックします。

3. Docker Desktop の設定で Updates を無効にします。

   • 右上のメニューバーで、歯車アイコンをクリックして設定を開きます。
   • 左サイドバーの「Software updates」タブを選択して、更新設定を表示します。
   • 「Automatically check for updates」のボックスの チェックを外します。
   • 「Automatically download updates」のボックスの チェックを外します。
   • 右下の「Apply & Restart」をクリックします。

4. Docker Desktop の設定で Extensions を無効にします。

   • 右上のメニューバーで、歯車アイコンをクリックして設定を開きます。
   • 左サイドバーの「Extensions」タブを選択します。
   • 「Enable Docker Extensions」のボックスの チェックを外します。
   • 右下の「Apply & Restart」をクリックします。

5. Docker Desktop の設定で Beta Features を無効にします。

   • 右上のメニューバーで、歯車アイコンをクリックして設定を開きます。
   • 左サイドバーの「Features in Development」タブを選択します。
   • 「Enable WASM」のボックスの チェックを外します。
   • 「Enable SOCKS proxy support」のボックスの チェックを外します。
   • 右下の「Apply & Restart」をクリックします。

6. Docker Desktop の設定で Notifications を無効にします。

   • 右上のメニューバーで、歯車アイコンをクリックして設定を開きます。
   • 左サイドバーの「Notifications」タブを選択します。
   • リスト内のすべての項目の チェックを外します。
   • 右下の「Apply & Restart」をクリックします。

7. 右上の内側のグレーの「X」アイコンを使用して、Settings メニューを閉じます。

8. Windows ユーザーを自動ログインするように設定します。

   • このステップには、セールスエンジニア、サポートエンジニア、または IT スペシャリストの支援が必要な場合があります。

9. Windows で hosts ファイルを 管理者として 開きます（C:\Windows\System32\drivers\etc にあります）。

   • これは多くの場合、スタートメニューを開いて notepad と入力し、Notepad アプリケーションを検索するのが最も簡単です。
   • Notepad アプリケーションを右クリックして「Run as administrator」を選択します。

10. 次のエントリを hosts ファイルの末尾にコピー＆ペーストし、各 <XXXXXXX MACHINE IP> を適切なマシンの IP に置き換えます。hosts ファイルを All files (*.*) のタイプで保存します（ファイル拡張子は付けないでください）。

    <CURRENT MACHINE IP> porta-socket.server
    <MAIN MACHINE IP> porta-db
    <BACKUP MACHINE IP> porta-db-2
    <ARBITER MACHINE IP> porta-db-3

    • 注: ここで必要な IP アドレスは 127.0.0.1 では ありえません。マシンの現在のネットワーク接続の IPv4 アドレスです。IPv4 アドレスは、ipconfig を PowerShell または cmd.exe で実行し、正しいネットワークアダプター（多くの場合 d3net）の IPv4 の値を見て確認できます。

11. 各マシンで mysql ポートを開くインバウンドルールを追加します。

    1. Windows Security —> Firewall & network protection —> Advanced Settings —> Inbound Rules —> Add Rule
    2. 「Ports」を選択して Next を押します。
    3. TCP を選択し、特定のローカルポートとして次を追加またはペーストします: 3306,3307,3308,33061,33062,33063
    4. 接続を許可します。
    5. すべてのシナリオでルールを適用します。
    6. ルールに「Porta MySQL Ports」という名前を付けます。

Porta On Prem のインストール

これでマシンは Porta On Prem を実行する準備が整いました。Porta On Prem Installation Guide に従ってインストールを完了してください。

---

トラブルシューティング

インストール

Porta のインストールのトラブルシューティングについては、Installation Troubleshooting を参照してください。

データベースレプリケーション

データベースのトラブルシューティングについては、Group Replication Troubleshooting を参照してください。

wsl --install -d Ubuntu-22.04 gives Error Code 0x80072ee7

WSL/Ubuntu のセットアップは、上記の WSL Setup and Ubuntu Installation セクションのオフライン手順を使用して行う必要があります。

WslRegisterDistribution failed with error: 0x80370102

このエラーは、wsl --install の後の再起動時に発生することがあります。
WSL の手順に従って BIOS で仮想化を有効にしてから、先ほどのインストール手順を続行してください。

wsl コマンドの実行時に ERROR: CreateProcessParseCommon:711: Failed to translate

Ubuntu がデフォルトのディストロとして設定されていることを確認してください。このエラーは多くの場合、Ubuntu ではなく Docker のディストロが使用されていることを示しています。ただし、wsl -l -v --all のような一部のコマンドは依然として機能していました。

このエラーは次のように表示されました。

PS C:\Users\administrateur> wsl
<3>WSL (27) ERROR: CreateProcessParseCommon:711: Failed to translate C:\Users\administrateur
<3>WSL (27) ERROR: CreateProcessParseCommon:757 : getpwuid(0) failed 2
<3>WSL (27) ERROR: UtilTranslatePathList:2866: Failed to translate C:\Program Files\WSL
<3>WSL (27) ERROR: UtilTranslatePathList:2866: Failed to translate C:\WINDOWS\system32
<3>WSL (27) ERROR: UtilTranslatePathList:2866: Failed to translate C:\WINDOWS
<3>WSL (27) ERROR: UtilTranslatePathList:2866: Failed to translate C:\WINDOWS\System32\Wbem
<3>WSL (27) ERROR: UtilTranslatePathList:2866: Failed to translate C:\WINDOWS\System32\WindowsPowerShell\v1.0\
<3>WSL (27) ERROR: UtilTranslatePathList:2866: Failed to translate C:\WINDOWS\System32\OpenSSH\
<3>WSL (27) ERROR: UtilTranslatePathList:2866: Failed to translate C:\Program Files\dotnet\
<3>WSL (27) ERROR: UtilTranslatePathList:2866: Failed to translate C:\Program Files\Docker\Docker\resources\bin
<3>WSL (27) ERROR: UtilTranslatePathList:2866: Failed to translate C:\Users\administrateur\AppData\Local\Microsoft\WindowsApps
<3>WSL (27) ERROR: UtilTranslatePathList:2866: Failed to translate C:\Users\administrateur\Ubuntu
Processing fstab with mount -a failed.
Failed to mount C:\, see dmesg for more details.
Failed to mount D:\, see dmesg for more details.
Failed to mount C:\, see dmesg for more details.
Failed to mount D:\, see dmesg for more details.

<3>WSL (27) ERROR: CreateProcessEntryCommon:334: getpwuid(0) failed 2
<3>WSL (27) ERROR: CreateProcessEntryCommon:505: execvpe /bin/sh failed 2
<3>WSL (27) ERROR: CreateProcessEntryCommon:508: Create process not expected to return

Docker Desktop - Unexpected WSL error

An unexpected error was encountered while executing a WSL command…

PowerShell（cmd や WSL ではなく）で wsl --status を確認し、「WSL2 is not supported with your current machine configuration」と表示される場合は、BIOS で仮想化を有効にする必要があります。このプロセスはマシンによって異なります。

Docker Installation Errors - “wsl update failed” or similar

Docker Desktop のインストール時に WSL 更新に関するエラーが発生した場合は、トラブルシューティングセクション「Error: 0x8024500c after wsl —update」の手順に従って WSL が最新であることを確認してから、Docker Desktop をアンインストールして再インストールしてください。

WSL 更新に関するエラーが引き続き発生する場合は、Docker Desktop をアンインストールして再インストールしますが、今回は Configuration で Use WSL2 instead of Hyper-V のチェックを外さないでください。

インストールが完了すると、Docker は再起動を促します。再起動後、Docker Desktop を再度起動します。

Settings に移動します。

「Use the WSL2 based engine」をチェックしてから、「Apply & restart」を選択します。

Error: 0x8024500c after wsl --update

Windows 10 でのインストールや、Microsoft Store を使用しない一部のインストールでは、このエラーが表示されます。PowerShell で wsl --version（または wsl --status）を実行して現在の WSL カーネルバージョンを確認し、5 で始まるはずの Kernel version のエントリを確認してください（WSL Version ではありません。それは別物です）。

カーネルバージョンが 5.10.102.2 以上でない場合は、カーネルを手動で更新する必要があります。

• Microsoft’s update catalog にアクセスし、最終更新日で並べ替えます。執筆時点では、最新バージョンは 5.10.102.2 です。
• 最新バージョンの .cab ファイルをダウンロードします。
• .cab ファイルをダブルクリックして、その中の .msi ファイルを抽出します。
• wsl_update_x64.msi を実行して、WSL2 カーネル更新プログラムをインストールします。
• PowerShell を管理者として開きます。
• PowerShell で dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart を実行して新しいバージョンを有効にします。
• wsl --set-default-version 2 を実行します。
• wsl --version（または wsl --status）で WSL のバージョンを確認します。
  • WSL バージョンは 2.X.X（2 で始まる）である必要があります。
  • カーネルバージョンは 5.10.102.2 である必要があります。

PowerShell で wsl --version（または wsl --status）を実行して WSL のバージョンを確認します。wsl --version および wsl --status コマンドが機能しない場合は、次を実行してみてください。

(Get-AppxPackage | ? Name -eq "MicrosoftCorporationII.WindowsSubsystemforLinux").Version

一覧表示されたバージョンが 2.0.14 以上でない場合は、次の手順（Updating WSL 2 without Microsoft Store に記載のとおり）に従って WSL を手動で更新する必要があります。

WSL Releases page in the Github repo から 2.0.14 の WSL アプリパッケージと msi リリースをダウンロードします。これはファイル拡張子 .msixbundle および .msi のアセットになります。

wsl --shutdown を実行して再起動し、WSL がまったく使用されていないことを確認します。

管理者 PowerShell を起動して次を実行します（ダウンロードした最新バージョンに合わせてパッケージ名を調整します）。

Add-AppxPackage <path.to>/Microsoft.WSL_1.0.0.0_x64_ARM64.msixbundle

Windows ストアに関する問題が発生した場合は、代わりに .msi ファイルを使用してインストールしてみてください。

インストール後、wsl --version または (Get-AppxPackage | ? Name -eq "MicrosoftCorporationII.WindowsSubsystemforLinux").Version で新しい WSL バージョンを確認します。

マシンを再起動します。