These are the instructions to get the docker image running for EIEIOO 2021. If you would like to participate in the workshops on Unix CLI, ROOT, PyROOT, GEANT4, and C++ but do not have these softwares on your system, we recommend you use this docker image and have it set up before the workshops begin (go through Prereqs, Quick Start, and Graphics Forwarding for you system).
- Prerequisites
- Quick Start
- Docker Tips and Tricks
- Graphics Forwarding from the Docker
- Notes for Developers
- Around 10 GB of free space on your system.
- Install Docker (Ubuntu, Windows, Mac)
- For Windows, make sure to get the latest version of Ubuntu (20.04) for WSL, as it has been confirmed to work.
Pull and run the latest image for the orientation:
open up a terminal and execute
sudo docker run -it soudk/eieioo2021which will download the container the first time, but otherwise just run the container once it's on your machine without downloading anything.
Once inside the container, execute source env.sh to get your environment ready (ROOT, GEANT4)
You can exit the container by typing exit or ctrl+D
If you'd like graphics forwarding to your screen, you will need to follow the instruction set out for your system in the section Graphics Forwarding from the Docker.
Go through the instructions outlined in the Docker installation in the order described.
In order for the Windows Subsystem for Linux (WSL) to work with the Docker application, you need them both to be running simultaneously.
The Docker GUI will also provide a simple way to see what current images are available and what containers are running.
It is recommended you use the CLI through the WSL Ubuntu application.
WSL can take a lot of resources to run, so be cognisent of this. Moreover, if you have Task Manager running in the back, you'll see just how much of your resources are being used.
When closing your instances, note that simply closing the window may not be enough. To end the Vmmem task (which is the virtual machine), run
wsl --shutdownin PowerShell.
You can view all running containers on your system by doing sudo docker container ls or add a -a flag at the end to view all (including stopped containers). Take note of the CONTAINER ID field.
Instead of exiting from a container, you can detach from it by doing ctrl+p then ctrl+q. This will allow you to rejoin the same container later an pick up where you left off.
You can reattach to a running container with
sudo docker attach [CONTAINER ID]using the ID you found when listing all your running containers.
You can mount a directory into the container so that you can write to your machine and save any results, notes etc... You produce in the container even after it is stopped and deleted.
sudo docker run -it -v /path/to/dir/onYourMachine/:/home/physuser/mountedDirectoryNameInDocker:rw soudk/eieioo2021Keep in mind that you may need to set the permissons on the folder you are mounting from your machine to read write and execute i.e. execute chmod 777 /path/to/dir/onYourMachine before mounting the volume.
Start your Docker container with
sudo docker run -it -p 8888:8888 --ip 0.0.0.0 soudk/eieioo2021 This maps the default port for Jupyter notebooks (8888) in the docker to your local machines port 8888.
Once inside the image, run
jupyter notebook --ip 0.0.0.0 --allow-root --no-browser --NotebookApp.token='sometoken'On your browser, you can now go to http://localhost:8888 and type in the "sometoken" you set in the jupyter notebook run command. Voila! Notebook away!
You can also add a -v flag to mount a directory with all your data from your machine into the docker by following the instructions in the section Mounting a Directory and interact with that data using the notebook.
You can name your containers when starting them up by doing
sudo docker run -it --name NAME soudk/eieioo2021where NAME is whatever you want to call your container. This way you can keep track of what the different containers on your system are for.
Delete all the stopped containers on your system with them by doing
sudo docker container pruneWhich will clear up resources from your system.
Alternatively, close only the container you want by
sudo docker container rm [CONTAINER ID]If the container is running it will not close, so you will have to either attach to it and exit it or use
sudo docker container rm -f [CONTAINER ID]to force it to close and be removed.
If you want to use graphical interfaces, which can be incredibly convenient, you will need to follow the instruction below for your system.
Start with running
xhost local:rootin your terminal. Then, run docker with the following command
sudo docker run -it -e DISPLAY=$DISPLAY -v /tmp/.X11-unix/:/tmp/.X11-unix soudk/eieioo2021which we can see sets the display accordingly and mounts the X11 directory.
Note that you will have to xhost local:root everytime you open a new terminal and want to do X11 forwarding with docker.
Windows is a bit annoying for getting graphical options running,since things were changed with the move to Windows Subsystem for Linux 2 (WSL2). Regardless, the first thing you'll want to do is update your package options by running
sudo apt updatein your WSL2 terminal. Then you'll get the graphical suite by running
sudo apt install x11-appsNow the tough part begins. This will involve giving the terminal access through your firewall. I found following this guide to work. Note it will require you to install VcXsrv aswell.
VcXsrv creates a virtual session for your ubuntu subsystem to forward to and will need to be run each time beforehand. The instructions give a command to run VcXsrv using the powershell, which I found worked for me in the following form:
& 'D:\Programs\VcXsrv\vcxsrv.exe' :0 -multiwindow -wgl -acThe pathway here will be different for you, just change it to where the program was installed. If this is too complicated, you can also just run the XLaunch application that is used to run VcXsrv. In that case, select "Multiple Windows > Start no client > Disable access control", where the first two options are the defaults, and the last option we enable that extra choice (Don't disable anything). You can save this when it asks, but that isn't necessary.
Once you have followed the instructions to completion, run sudo apt install x11-apps and check that the X11 forwarding works by running xclock in your terminal. This should pop up an anologue clock on your screen.
If the clock appears on your screen, you are pretty much done! The only difference is that when you are running your docker client, I found starting it using the following command set up the proper display,
docker run -it -e DISPLAY=$DISPLAY soudk/eieioo2021This is assuming the $DISPLAY variable is set as the guide recommended. To check that it worked, repeat the above steps of installing graphical suite and running xclock.
You will need to install XQuartz version >2.7.10, you can do this with homebrew or by installing a .dmg file
Install homebrew by following the instructions here.
Next, you'll want to get XQuartz version >2.7.10 by running
brew install xquartzin your terminal.
You can find and install the .dmg file here.
Once you have XQuartz installed (using either homebrew or .dmg method) you can follow the instructions below.
Run open -a XQuartz and click on the XQuartz logo that popped up in your dock.
Go to XQuartz (top left of your screen) then Preferences.
Click on the Security Tab in Preferences, and checkmark the "allow conections from network clients" box.
run xhost + 127.0.0.1 in the xquartz terminal. You should see a message saying it's been added to the list of secure connections.
Close XQuartz by quitting it from the dock and close your terminal fully.
Restart your terminal and run XQuartz again with
open -a XQuartzThen run the command
xhost + 127.0.0.1which will allow docker to access your screen.
Note: if you ever quit XQuartz you will have to allow docker access to your screen again with xhost + 127.0.0.1.
Now you can run your docker image with the flag -e DISPLAY=host.docker.internal:0
So for this docker image
sudo docker run -it -e DISPLAY=host.docker.internal:0 soudk/eieioo2021You can run xclock once inside the docker image to check that the graphics forwarding is working properly.
The rest of these notes are directed towards those who are hoping to contribute to the development of the docker image itself or its documentation. You do not need to worry about this section if you are a user.
DockerHub link: https://hub.docker.com/r/soudk/eieioo2021
After cloning the StudentDocker repository into your machine, you will need to run
git submodule syncthen
git submodule update --init --recursiveTo populate the GEANT4 and ROOT submodules in the repository.
finally, update the modules with
git submodule update --remote --mergeYou can then build the docker image yourself by doing
docker build -t [IMAGE NAME] ./ where [IMAGE NAME] is whatever you want to call your image (must be all lower case).
This command will take a couple hours to run. The final image will be 8-9 GB so beware! If you don't want to wait forever, you can edit the Dockerfile nd comment out the ROOT and GEANT4 parts, but this will leave you with an image without either softwares.
Run sudo docker build -t [IMAGE NAME] ./ to build the image.
After you build the image, you can run docker images to see all your downloaded images. Take note of the [IMAGE ID] for your new image.
Then run your new container by doing
sudo docker run -it [IMAGE NAME]You can also replace [IMAGE NAME] with the [IMAGE ID] you saw when you listed all your images earlier.
If you would like to contribute to this image, please open an issue on the repository on GitHub and you will be given permissions to modify the files.
- Thomas McElroy
- Soud Al Kharusi
- Dilraj Ghuman
- Chris Jillings
- Jean-François Caron