Specific instructions for Windows installation

Fed-BioMed requires Windows 11 and WSL2. It can run on a physical machine or a virtual machine.

This documentation gives the steps for a typical Windows 11 installation, steps may vary depending on your system.

Step 0: (optional) virtual machine

Skip this step if running Windows on a physical (native) machine, not a virtual machine.

Requirement : choose an hypervisor compatible with other installation

VMware Workstation 15.5.5 or above can be used, it is compatible with HyperV. We successfully ran Fed-BioMed with VMware Workstation 16.
VirtualBox 6.1 cannot be used as it conflicts with Hyper-V "Virtual Machine Platform" which is needed for WSL2

Tips :

enable virtualization engine for your VM. For VMware Workstation 16, check the boxes in Virtual Machine Settings > Hardware > Processors > Virtualization Engine
allocate 8GB RAM or more to the VM, this is needed for conda PyTorch installation. For VMware Workstation 16 this can be done in Virtual Machine Settings > Hardware > Memory

Step 1: Windows

Requirement : tested under Windows 11 21H2, though Windows 10 version 2004 and higher (Build 19041 and higher) also support WSL2 and Docker Desktop.

update Windows
reboot Windows

You can run Fed-BioMed on any Windows 11 edition including Home edition if you don't use optional containers/dockers functionality.

Requirement: if using optional containers/docker, then Windows Enterprise, Pro or Education edition is needed for Hyper-V functionality, which is not present in Home edition.

Requirement : Hyper-V "Virtual Machine Platform" activation

enable Hyper-V
reboot Windows

Step 2: WSL2

WSL (Windows Subsystem for Linux) is a tool that allows to run Linux within a Windows system. Version 2 of WSL is needed for docker. We successfully tested Fed-BioMed with Ubuntu-24.04 distribution.

Requirement : WSL version 2

activate WSL with main menu > enter 'Turn Windows Feature on or off' > and click on 'Windows Subsystem for Linux' checkbox
reboot Windows
set version 2 in a Windows command tool
```
cmd> wsl --set-default-version 2
```
reboot Windows
Optional: you may need to run
```
cmd> wsl --install
```

Requirement : a WSL distribution, eg Ubuntu

install a distribution in a Windows command tool
```
cmd> wsl --install -d Ubuntu-24.04
```
if required by install, update the WSL2 kernel: in *main menu > enter 'Windows Update' > select 'Advanced Options' > activate 'Receive updates for other Microsoft products'. Then in Windows Update, install the last version of WSL2.
reboot Windows

Check that WSL uses version 2 and Ubuntu is installed in a Windows command tool :

cmd> wsl -l -v
  NAME                   STATE           VERSION
* Ubuntu                 Running         2

Open a WSL session from a Windows command tool :

cmd> wsl
user@wsl-ubuntu$

Step 3: docker (optional, required if containers/VPN needed)

Requirement : docker and docker compose

Install Docker Desktop on the Windows machine :

install Docker Desktop in Windows. Check the product license.
reboot Windows

Setup docker in your WSL Ubuntu :

open an administrator session in WSL Ubuntu :
```
user@wsl-ubuntu$ sudo bash
root@wsl-ubuntu#
```
- install docker engine as admin (root) account in WSL Ubuntu. Please note that docker container run hello-world will not work until we complete the steps below - if you use an account named USER under Ubuntu, authorize it to use docker by typing under an admin (root) account in WSL Ubuntu :
```
root@wsl-ubuntu# adduser USER docker
```
open a new WSL Ubuntu terminal so that it is authorized to use docker

Check that you can use docker with your user account under Ubuntu :

user@wsl-ubuntu$ docker container run hello-world

Step 4: conda

It is recommended to run fedbiomed under an environment manager. conda has been tested for Windows WSL2 installation of Fed-BioMed.

Requirement : conda installed in Ubuntu and configured for your user account

install Miniconda under Ubuntu, using your user account
during installation, answer Yes to question “Do you wish the installer to initialize Anaconda3 by running conda init?”
activate conda for your Ubuntu session
```
user@wsl-ubuntu$ source ~/.bashrc
```

Step 5: Fed-BioMed

Follow Fed-BioMed Linux installation tutorial with a pip install fedbiomed[researcher,node,gui] or shrink down to a specific component (node, researcher, gui).

When running for the first time, a Windows defender pop up may appear (triggered by docker), choose "authorize only on private network".

Performance issue

To ensure Fed-BioMed performance in WSL2, be sure to use the native WSL2 Linux filesystem (in /home/login), not the Windows filesystem (in /mnt/c/Users/login), both for cloning the library and storing datasets. We experienced 10-50 time slower execution with native Windows filesystem. This point is documented by Microsoft

You may also need to increase the memory available to WSL2. By default, only 50% of the host's RAM is made available.

Troubleshooting

Step 2 troubleshooting

Error 1: `The virtual machine could not be started because a required feature is not installed`

When installing Linux, if this error happens:

Installing, this may take a few minutes...
WslRegisterDistribution failed with error: 0x80370102
Error: 0x80370102 The virtual machine could not be started because a required feature is not installed.

This means either you need to enable virtualisation on the bios of your computer or to enable Hyper-V : for the latter, go in

main menu > enter 'Turn Windows Feature on or off' > and click on Hyper-V checkbox

Then restart Linux distribution installation.

Error 2: `failed with error: 0x80004005`

If this error happen when installing a Linux disribution:

WSLRegisterDistribution failed with error: 0x80004005

Press Win + R: it will open a window named Run tasks
Enter REGEDIT and hit OK
Navigate to : HKEY_LOCAL_MACHINE\CurrentControlSet\Services\LxssManager
Set the value Data to 2 and exit REGEDIT.
reboot the machine and see if it is working

Step 4 troubleshooting:

If you cannot launch conda after restarting your shell, you may need to activate through source. From your miniconda3 installation folder, run:
```
source miniconda3/bin/activate
```
conda will then be activated.

Step 5 troubleshooting:

If we encounter 'Operation not permitted' error on cloning git repository, you may follow below steps.

Error --> fatal: could not set 'core.filemode' to 'false'

Launch Ubuntu WSL.
Create the file /etc/wsl.conf if it doesn't exist.
Open the file (nano /etc/wsl.conf) and add the below lines: [automount] options = "metadata"
Save the file and shoutdown WSL
Relaunch Ubuntu WSL

If the problem still persists, you may try restarting the machine and then execute git clone command.

We detail here two common issues encountered when instlling and running Fed-BioMed.

If launching Fed-BioMed researcher fails with a message mentioning a display error, you may need to use an alternate IP address. There are two ways of fixing this:
1. run jupyter jupyter notebook --ip $(python3 -c "import subprocess; subprocess.run(['hostname', "-I"], text=True).sdtout") and connect to the IP address given by jupyter-notebook.
2. or you can just connect to the IP address given by the command ip addr | grep eth0 | grep inet instead of connecting to localhost.
If Fed-BioMed fails with a message mentioning a System.Management.Automation error you may need to give WSL which browser to use. Set the BROWSER environment variable to the path to the browser. For example to use Microsoft Edge the path and command are commonly :
```
user@wsl-ubuntu$ export BROWSER=export BROWSER=/mnt/c/Program\ Files\ $x86$/Microsoft/Edge/Application/msedge.exe
```