Instructions for Running FermiBottle on Windows Systems

Install WSL2

Requirements: Admin rights on your machine, Windows 10 (build 18362 or higher)

Docker requires Windows Subsystem for Linux 2 (WSL2) to be set up in order to use it as a virtualization backend. While Docker also allows the use of a Hyper-V backend this is not recommended or supported by the FSSC.

Follow the instructions provided by Microsoft here: Windows Subsystem for Linux Installation Guide for Windows 10

Make sure WSL2 is set as your default version and install either the Ubuntu or Debian distribution app via the Microsoft Store. After installation is complete open the distro via its associated app and finish setup by providing the username/password combination you'd like to use within the linux environment. This does not have to be the same as your Windows login.

Install Docker

Once WSL2 is completely set up, download and install Docker Desktop for Windows from the docker download page: Docker Desktop

After installation has been completed and you've finished all necessary reboots, open the Docker Desktop program navigate to the settings. Click the "Resources" tab and open the "WSL Integration" settings. Make sure the box labeled "Enable integration with my default WSL distro" is checked and that any additional distros you wish to have docker enabled in are toggled on. Once this is done click the "Apply & Restart" button.

You should now have access to docker within your WSL distro of choice. Test this by opening the distro app and trying the docker command in the shell. This should print a list of command options for use with docker.

Installing an XWindows server and setting up forwarding

You will need an XWindows server running on your Windows 10 machine to allow the container/wsl environment to properly open GUI windows. This has been successfully tested using the VcXsrv Windows X Server. Download the software from the SourceForge link and install it.

In your Linux distro install the openssh-server package. You can do this with the command sudo apt-get install openssh-server. Confirm the installation and wait for it to finish. Once that is done, set the proper display settings by running these two commands in the shell:

export DISPLAY=$(awk '/nameserver / {print $2; exit}' /etc/resolv.conf 2>/dev/null):0

export LIBGL_ALWAYS_INDIRECT=1

It is HIGHLY RECOMMENDED that you add these two commands to the bottom of your ~/.bash_profile so that they are automatically run each time the distro is launched.

Starting the Xserver

To start the Xserver in Windows 10 for the first time, run XLaunch and make the following selections on the various dialog boxes:

1. No changes on the first screen, click "Next".
2. No changes on the second screen, click "Next".
3. Select "Disable Access Control" on screen three. Click "Next".
4. If you want to not have to go through this each time, select "Save Configuration" and name your .xlaunch file. You can then just double click this file to start in the future.
5. Click "Finish" to start the X11 server.

You now have Windows 10 prepared to setup and run the Fermibottle Docker container.

Your Windows 10 directories are accessible within the Linux distro via the /mnt directory.

All of the following instructions are to be done within the Linux distro

Acquire the Docker Image

The FermiBottle image is an approximately 3 GB file that is hosted on Docker Hub. You can download it using a Docker pull command:

docker pull fssc/fermibottle

Prepare your shared directory

The shared directory is a folder on your host machine whose contents are also visible inside the container. Our default instructions are going to ensure that everyone is working from the same shared directory in the same location, but if you are clever you can point this anywhere else on your machine.

mkdir $HOME/shared

Create a container from the FermiBottle image (Linux)

1. Create a new FermiBottle container by copying this block of code into your command line and running it:

docker create -it --init \
-e HOST_USER_ID=`id -u $USER` \
-e DISPLAY=$DISPLAY \
-v /tmp/.X11-unix:/tmp/.X11-unix \
-v "$HOME/shared":/shared \
-p 8888:8888 \
fssc/fermibottle

The big string of numbers and letters that gets printed out is your Container ID. That can be hard to remember so you may instead want to use the NAME. These should both be listed for you if you run docker ps -a.

If you were successful, we recommend you Do Not make duplicate containers by running docker create again. It can be frustrating if you lose track of which one all of your work was done in if it wasn't saved to the shared directory.

Continue to Using the FermiBottle container.