1 of 17

LIP Internships 2021

Docker installation instructions

2 of 17

Context

NOTE 1: You only need to follow this guide if you don’t have an account in the LIP computers. Check with your supervisor or the LIP IT team if you are not sure

NOTE 2: You only will need Docker installed in your personal computer and a ROOT docker container if you want to participate in the following tutorials:

  • C++
  • ROOT basics
  • ROOT intermediate
  • ROOT analysis/fitting
  • Neutrinos hands-on

These slides contain instructions for Windows, MacOS and Linux

The instructions and scripts used are also available in this git repository

If you have problems or questions, feel free to use the #docker channel on Slack

2

3 of 17

Windows

  • Enable virtualization in the BIOS settings of your computer
    • Open the Windows Task Manager (Ctrl+Alt+Del) and go to the Performance tab
    • Check if Virtualization is Enabled (see image below)
    • If not, restart your computer, open the�BIOS settings (usually by pressing F2,�F10 or Del while booting), find the CPU�settings and enable virtualization
    • Save the BIOS settings and restart

3

4 of 17

Windows

  • Install WSL2
    • WSL stands for Windows Subsystem for Linux, and is a way to run a Linux system inside Windows
    • Open PowerShell as Administrator -- hit the Start/Windows key, type powershell and select “Run as administrator” (see screenshot in the next slide)

4

5 of 17

Windows

  • Install WSL2
    • Run the following command, to enable WSL 1 (note that you can click the right mouse button to paste this text inside the powershell window)�dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
    • WSL 2 uses a lightweight VM, so you need to enable the Virtual Machine feature available in Windows 10 version 1903 and higher. In the same Powershell window run:�dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
    • You should see something similar to what is shown in the image.
    • Now it’s time for a restart, to ensure everything installed successfully

5

6 of 17

Windows

  • Install WSL2
    • Download the WSL2 Linux kernel update package for x64 machines and install it.
    • If you see an error message, make sure you followed the previous steps correctly and restarted your computer
    • The installer runs very quickly, and hopefully you'll see a confirmation screen
    • Set WSL 2 as your default version -- open a PowerShell window and type

wsl --set-default-version 2

We actually don't need to install a Linux distribution to use Docker Desktop, but if you want to shell into Linux directly, you'll need to install one. You can install a distribution directly from the Microsoft Store (not covered in these instructions).

6

7 of 17

Windows

  • Install Docker
    • Download and install Docker for Windows (this is about 500 MB)
    • On the first screen, ensure you keep "Install required components for WSL 2" checked
    • At the end it will ask you to log out of your Windows account to complete the installation
    • The Docker Desktop installer will automatically log you out of your Windows account on completion. When you sign back in, you'll get a notification that Docker is starting the Linux Containers WSL 2 backend. Eventually, the main Docker Desktop window will pop up, and offer you a short tutorial
    • You are now ready to try the ROOT docker container!

7

8 of 17

Windows

  • Get the ROOT image
    • The ROOT docker images are available in the docker hub, along with more instructions
    • Open a terminal (PowerShell or Windows Terminal) and type�docker run --rm -it rootproject/root
    • The first time you run this command it will have to download and expand the ROOT image. This will take a few minutes depending on your network connection
    • Once it finishes you should find yourself inside the ROOT command line prompt �(you can exit by typing .q)
    • To get a Linux terminal instead, type: docker run --rm -it rootproject/root bash

8

9 of 17

Windows

  • Configure the ROOT docker container
    • Once you exit the container all the changes you made are lost. To avoid this you need to share a local folder with the docker container. Changes inside that folder are permanent, so you can use it to store your work
    • Open the Docker utility and select images. You should see the root image there
    • Click “Run”, and you’ll get a dialog where you can name the container (e.g. my-root). You can also select a folder in your computer (click the “...”, it’s better to create a folder specifically for this) and mount it to a folder inside the container (e.g. /shared)
    • Click “Run” to start the container. If you go to the “Containers” section of the Docker utility your container should now be listed!
    • You can enter the container directly in the Docker interface by clicking the CLI icon (first icon on the right), or (preferably) in a separate terminal (MobaXterm, Powershell or Windows Terminal) by typing �docker exec my-root bash
    • See the next slide to learn how to start the container with support for graphical windows

9

10 of 17

Windows

  • Open X windows
    • To open graphical (usually called X-) windows from the container �(e.g. plots from ROOT) we need to install an X server for Windows
    • Install MobaXterm (see pre-tutorial instructions)
    • Open MobaXterm, go to Settings->Configuration->X11 and change “X11 remote access” to “full”. Click Ok, MobaXterm will tell you it will restart the X server. You only need to do this the first time you use MobaXterm
    • Make sure you’ve started your my-root container with a shared folder (see Configure the ROOT docker container)
    • On the main MobaXterm area, click “Start local terminal”. In the initial message displayed it will tell you the IP address for DISPLAY -- you will need this for the next step
    • Enter the container from the MobaXterm terminal by typing�docker exec -it -e DISPLAY=192.168.0.106:0.0 my-root bash�(replace the IP address by the one indicated in your MobaXterm session)
    • Type root to start ROOT, and now open a graphical window with:�new TBrowser�You should see a graphical window opening! That’s it, you’re ready for the tutorials, quit root by typing .q

10

11 of 17

Windows

  • C++ in the ROOT docker container
    • Install a simple code editor so you can edit the code used in the tutorials in Windows. Notepad++ is a good option (notepad-plus-plus.org)
    • Open the editor, paste the sample code above in a new file to get a “Hello World” example, and save it inside the folder you shared with the container (e.g. hello.cpp -- remember to correctly select the file type)
    • Now you can compile and run this code inside the container. In the MobaXterm terminal, type:� cd /shared� g++ hello.cpp -o hello� ./hello
    • If all goes well you should see a “Hello world” message being displayed!

11

#include <iostream>

using namespace std;

​

int main(){

cout << "Hello world!" << endl;

return 0;

}

12 of 17

MacOS

  • Install Docker Desktop for Mac and follow the instructions on the page
  • Test your docker installation. Open a terminal and type:�docker --version�(should return something like Docker version 19.03.13, build 4484c46d9d)
  • Make sure you have XQuartz installed, you’ll need it to open X11 windows from the Docker image
  • Change XQuartz settings to allow remote connections to open X windows: �XQuartz -> Preferences -> Security -> Allow connections from network clients�It’s a good idea to log out and back in after this step
  • Create a local folder for your work. This folder will be shared between your local (MacOS) system and the docker image, e.g.�mkdir -p ~/docker/tutorials�cd ~/docker/tutorials
  • To make life easier, download and save these two scripts to the folder you just created: �setup_docker.sh and run_docker.sh
  • Start the container by running source setup_docker.sh �(the first time it will take a while, as it needs to download the image)
  • Enter the container by running source run_docker.sh -- the local folder is shared under /shared

12

13 of 17

MacOS

  • Testing your ROOT container
    • Open your favorite code editor on your Mac (e.g. XCode, Sublime Text), create a new file and paste the code of the Hello World example above. Save it in the shared folder (~/docker/tutorials) as hello.cpp
    • After entering the container in the terminal (with source run_docker.sh), go to the shared folder, compile and execute the code�cd /shared�g++ hello.cpp -o hello�./hello
    • You should see an Hello world! message in the terminal

13

#include <iostream>

using namespace std;

​

int main(){

cout << "Hello world!" << endl;

return 0;

}

14 of 17

MacOS

  • Graphical (X) windows in your container
    • Enter the container by typing source run_setup.sh �in the terminal
    • Start the ROOT application. Just type root
    • You should now see the ROOT command prompt
    • To test opening a graphical window, type:�new TBrowser
    • You should see a ROOT graphical window. You can now leave ROOT by typing .q
    • If you got an error instead:
      • Did you install XQuartz?
      • Did you change the XQuartz settings and logged out / back in afterwards?
      • Try a full system restart
      • Ask for help in the #docker Slack channel

14

15 of 17

Linux

  • Install docker for your Linux distribution
    • This tutorial works for Ubuntu releases 16.04 through 21.04, should also work for other variants such as Linux Mint
    • Installing from the repository should be the easiest and safest way
    • Make sure to also follow the post-installation steps, in particular create a docker group and add your user to it, and configure Docker to start on boot
  • Test your docker installation. Open a terminal and type:�docker --version�(should return something like Docker version 19.03.13, build 4484c46d9d)
  • Create a local folder for your work. This folder will be shared between your local (MacOS) system and the docker image, e.g.�mkdir -p ~/docker/tutorials�cd ~/docker/tutorials
  • To make life easier, download and save these two scripts to the folder you just created: �setup_docker.sh and run_docker.sh
  • Start the container by running source setup_docker.sh �(the first time it will take a while, as it needs to download the image)
  • Enter the container by running source run_docker.sh -- the local folder is shared under /shared

15

16 of 17

Linux

  • Testing your ROOT container
    • Open your favorite code editor on your computer (e.g. gedit, emacs), create a new file and paste the code of the Hello World example above. Save it in the shared folder (~/docker/tutorials) as hello.cpp
    • After entering the container in the terminal (with source run_docker.sh), go to the shared folder, compile and execute the code�cd /shared�g++ hello.cpp -o hello�./hello
    • You should see an Hello world! message in the terminal

16

#include <iostream>

using namespace std;

​

int main(){

cout << "Hello world!" << endl;

return 0;

}

17 of 17

Linux

  • Graphical (X) windows in your container
    • Enter the container by typing source run_setup.sh �in the terminal
    • Start the ROOT application. Just type root
    • You should now see the ROOT command prompt
    • To test opening a graphical window, type:�new TBrowser
    • You should see a ROOT graphical window. You can now leave ROOT by typing .q
    • If you got an error instead:
      • Try a full system restart
      • Ask for help in the #docker Slack channel

17