龙讯旷腾 pwmat Wiki

本页面只读。您可以查看源文件，但不能更改它。如果您觉得这是系统错误，请联系管理员。
====== PWstudio CPU version - Windows 11 (WSL2) installation guide ======

Applies to: Windows 11\\

<wrap important>
Before you start, we strongly recommend reading [[en:pwstudio:readme|Read this before installing PWstudio]] first to get the big picture.
</wrap>

----

<wrap em>Starting the PWstudio CPU container with wslc</wrap>

<wrap tip>
The section below shows how to start the PWstudio CPU container using wslc (the container tool built into WSL).
</wrap>

===== 1. Install/update WSL =====

A friendly note:
All the commands below are run in **PowerShell**.

**If you're installing on your own computer:** right-click the Start button and choose to open PowerShell as administrator; or search for ''PowerShell'' in the "Start" menu, right-click it and choose "Run as administrator" to open the terminal.

**If you're installing on a server with a Windows system installed:** you first need to connect to the remote server following the steps below.

> (1) Open the Remote Desktop Connection tool
> • Press the Win + R keys on your keyboard to open the "Run" dialog box.
> • In the dialog box that pops up, type mstsc, then click "OK" or press Enter.
>
> (2) Enter the server information
> • In the "Remote Desktop Connection" window that pops up, find the "Computer" field.
> • Enter the target server's IP address: for example 192.168.97.23.
> • Click "Show Options" in the lower-left corner to expand more settings. In the "User name" field, enter the corresponding username, for example lxkt.
> • Click "Connect".
>
> (3) Enter the login credentials
> • The system pops up a "Windows Security" window, asking for the username's password as the credential.
> • In the "User name" field, enter lxkt (if you already filled it in the previous step, it will be shown automatically here).
> • In the "Password" field, enter the password, for example lxkt.
> • Once you've confirmed the information is correct, click "OK".
>
> (4) Confirm the security certificate
> • If this is the first time you're connecting to this server, the system may prompt "Cannot verify the identity of the remote computer. Do you want to connect anyway?".
> • This is a normal security reminder — after checking that the IP address is correct, click "Yes" to continue the connection.
>
> After the connection succeeds, you can log into the remote server's Windows desktop. On the remote server, right-click the Start button and open PowerShell as administrator; or search for ''PowerShell'' in the "Start" menu, right-click it and choose "Run as administrator" to open the terminal.

1. If the system doesn't have WSL yet, you need to run the following command first to install it
<code powershell>
wsl --install
</code>

2. Update to the WSL pre-release build: run the following command

<code powershell>
wsl --update --pre-release
</code>

3. Restart the WSL service: after the update finishes, run this command to apply the change

<code powershell>
wsl --shutdown
</code>

4. Verify that wslc is available: close and reopen your terminal (PowerShell or Windows Terminal)

<code powershell>
wslc --version
</code>

If you see output with a version number (e.g. 2.9.3.0), you're good to continue to the next step.

===== 2. Install the server.py service on the host machine =====

Installation instructions: click the link, [[en:pwstudio:serverwin|Installing the server.py service on Windows]], and follow the guide to set up the license service before moving to the next step.

===== 3. Import the image =====

<code powershell>
wslc pull ccr.ccs.tencentyun.com/lxkt/qflowcpu:latest
</code>

This step downloads the PWstudio CPU image, which is fairly large — depending on your network speed it may take anywhere from a few minutes to over ten minutes, so please be patient.

>**Note: if you get an error when pulling the image** such as "The operation could not be started because a required feature is not installed. Error code: HCS_E_SERVICE_NOT_AVAILABLE",
>the core cause of the HCS_E_SERVICE_NOT_AVAILABLE error is that the virtualization service (vmcompute) required by WSL2 is not working properly. wslc relies on WSL2's virtualization to create and manage containers, so when the underlying service is unavailable, the wslc pull command will fail.
>
>**Solution: change the WSL2 network mode to mirrored**
>This makes WSL2 share the same network stack with Windows, which resolves the TLS issue.
>
>(1) In the File Explorer address bar, type %UserProfile% to enter the user directory.
>(2) Create or edit a .wslconfig file (note the dot in the file name).
>(3) Paste the following content into the file:
><code powershell>
ini
[wsl2]
networkingMode=mirrored
dnsTunneling=true
firewall=false
</code>
>(4) Save the file, then close all WSL-related terminals and programs.
>(5) In PowerShell, run wsl --shutdown to restart WSL.
>(6) Reopen the terminal and try wslc pull ccr.ccs.tencentyun.com/Lxkt/qflowcpu:Latest again.
>
>If it succeeds, the problem is solved.

===== 4. Start the container =====

Before starting the container, you first need to run ''ipconfig'' in the host's PowerShell terminal to check the IP of the corresponding WSL virtual NIC (take the IPv4 address under the Ethernet adapter vEthernet (WSL (Hyper-V firewall))).

<note tip>Note: if after running ipconfig on the host you can't find the IP of the WSL virtual NIC, you need to install Ubuntu; you can install it with the following command

<code bash>
wsl --install -d Ubuntu
</code></note>

The 172.20.192.1 in the first line of the container start command below is the IP of the WSL virtual NIC found with ipconfig

In PowerShell:

<code powershell>
wslc run -d --name qflowcpu -e SERVERIP=172.20.192.1 `
  -v $env:TEMP\pwmat:/var/tmp/pwmat_host_secret:ro `
  --ulimit memlock=-1:-1 --ulimit stack=-1:-1 --shm-size=128G `
  -e SELINUX=disabled -p 80:80 -p 81:81 -p 2297:2297 -p 5010:5010 `
  --hostname=mstation ccr.ccs.tencentyun.com/lxkt/qflowcpu:latest
</code>

In cmd:

<code powershell>
wslc run -d --name qflowcpu -e SERVERIP=172.20.192.1 ^
  -v %TEMP%\pwmat:/var/tmp/pwmat_host_secret:ro ^
  --ulimit memlock=-1:-1 --ulimit stack=-1:-1 --shm-size=128G ^
  -e SELINUX=disabled -p 80:80 -p 81:81 -p 2297:2297 -p 5010:5010 ^
  --hostname=mstation ccr.ccs.tencentyun.com/lxkt/qflowcpu:latest
</code>

<WRAP center round info 10%>
Note: when starting the container in PowerShell or cmd, you must change the IP to the one for the WSL virtual NIC found with ipconfig, otherwise job submission will fail. For the command to start the container with a specified IP, you can also refer to [[en:pwstudio:qa:q106|item 2]] on that page.

The 172.20.192.1 in -e SERVERIP=172.20.192.1 ` needs to be changed to the IP of the WSL virtual NIC found with ipconfig

Or set up mirrored networking
</WRAP>

Pick one of the two commands above (PowerShell or cmd) — just run the one that matches the terminal you usually use; don't run both. If there's no error, it will print a long string of characters (the container ID), meaning the container has started.

<WRAP center round todo 10%>
On Windows:

Check the running container(s) with the following command:

<code bash>
wslc ps
</code>

Check all containers (running or stopped) with the following command:

<code bash>
wslc ps -a
</code>

After running it you'll see a table. If there's a row with ''qflowcpu'' under the ''NAMES'' column and ''Up ...'' under the ''STATUS'' column (e.g. "Up 5 minutes"), the container is running normally.

Start a container that already exists but is currently stopped:

<code bash>
wslc start qflowcpu
</code>

Before starting the container, if a container with the same name is in use, you need to stop and delete the old one first:

<code bash>
wslc stop qflowcpu
</code>

Delete the old container of the same type:
<code bash>
wslc rm qflowcpu
</code>

After stopping and deleting it, just run the ''wslc run'' command above again.

<WRAP center round alert 60%>
  - Deleting a container also deletes the data inside it❗
  - Qflow workflows inside the container cannot be exported
</WRAP>

</WRAP>


===== 5. Logging into the container, uploading/downloading files =====

  * Log in / upload / download via an SSH client<wrap notice>recommended</wrap>

^ Address        ^ Port  ^ Username  ^ Password             ^
| [host IP]  | 2297    | pwmat   | PWmat2022        |
| [host IP]  | 2297    | root    | PWmatSimplyBest  |

In the table above, replace ''[host IP]'' with 127.0.0.1; fill in everything else exactly as shown in the table, no changes needed.


<wrap tip>
If the installation above was done by connecting from your own computer to a remote server's Windows, then here you need to be on the remote server: log in to PowerShell as an administrator, and log directly into the container with ssh username@127.0.0.1 -p 2297 (it can't be reached via 127.0.0.1 from your local machine).
</wrap>

**Note: once you've logged into the container, when submitting jobs from the command line inside the container, you can use the slurm.sh script file in example01 to submit jobs, but you need to change the IP in the script to the IP of the WSL virtual NIC found with ipconfig — that is, in the last job-submission command of the script ( mpirun -np $SLURM_NPROCS PWmat -host 172.20.192.1 50001 | tee output), change the IP (172.20.192.1) to the IP of the WSL virtual NIC**

===== 6. Accessing Qstudio and Qflow =====

From this step on, switch to using a **web browser** (Chrome or Edge recommended). Access address: %%http://[host IP]%% — for the host IP, just use 127.0.0.1.

**Note:** if it was installed on a remote server, this step needs to be done in the remote server's browser.

^ Account ^ Password ^
| 15000000000 | PWmat2022 |

If pasting the password says it's wrong, this may be a browser compatibility issue — just type the password manually instead.

~~DISCUSSION:off~~


----

**If you installed by connecting from your own computer to a remote server and want to access it from your local machine, see the section below:**

If you installed it on your own computer, both the access method above and the one below work. If you installed it by connecting from your own computer to a remote server, you only need to access it on the remote server, using the method above (you can't access it directly from your local machine). But if you want to access it directly from your local machine, you can use the method below (accessing via the real host IP) — this method works both when accessing from the remote server and when accessing directly from your local machine:

Specifically:

When starting the container, it needs to be started the following way (compared with the container start command above, three 0.0.0.0 prefixes have been added):

<code bash>
wslc run -d --name qflowgpu -e SERVERIP=172.20.192.1 `
  -v $env:TEMP\pwmat:/var/tmp/pwmat_host_secret:ro `
  --ulimit memlock=-1:-1 --ulimit stack=-1:-1 --gpus all --shm-size=128G `
  -e SELINUX=disabled -p 0.0.0.0:80:80 -p 0.0.0.0:81:81 -p 0.0.0.0:2297:2297 -p 5010:5010 `
  --hostname=mstation ccr.ccs.tencentyun.com/lxkt/qflowgpu:latest
</code>

After it starts successfully,

**To access the container:** you can access and log in from your local PowerShell, local Xshell or MobaXterm, the remote server's PowerShell, the remote server's Xshell, etc. When accessing, the host IP can be obtained with the ipconfig command — it's the IPv4 address under the Ethernet adapter Onboard LAN2, i.e. the real host IP (e.g. 192.168.97.23). For the port, username and password, refer to the container access table above.

**To access qflow and qstudio:** access using the real host IP. Specifically, go to %%http://[host IP]%% directly in your local browser / on the remote server (host IP: the IPv4 address under the Ethernet adapter Onboard LAN2, obtained with the ipconfig command).

~~DISCUSSION:off~~