/!\ IMPORTANT: this is a set of hands-on tutorials: participants are expected to bring a laptop and pre-install software in advance to make the best use of time during the proposed tutorials. If for some reason you are unable to fulfill this pre-requisite, try to seat close to an attendee that is able to perform these tasks.

Note: in the following instructions, terminal commands are prefixed by a virtual prompt $>which obviously does not belong to the command.

Online accounts

Kindly create in advance the various accounts for the cloud services we might use, i.e.:

UL HPC account

You need to have an account on our platform. See https://hpc.uni.lu/users/get_an_account.html

Software

Install the following software, depending on your running platform:

Platform Software Description Usage
Mac OS Homebrew The missing package manager for macOS brew install ...
Mac OS Brew Cask Plugin Mac OS Apps install made easy brew cask install ...
Mac OS iTerm2 (optional) enhanced Terminal
Windows MobaXTERM Terminal with tabbed SSH client
Windows Git for Windows I'm sure you guessed
Windows SourceTree (optional) enhanced git GUI
Windows/Linux Virtual Box Free hypervisor provider for Vagrant
Windows/Linux Vagrant Reproducible environments made easy.
Linux Docker for Ubuntu Lightweight Reproducible Containers
Windows Docker for Windows Lightweight Reproducible Containers

Follow the below custom instructions depending on your running platform and Operating System.

Mac OS X

Once you have Homebrew installed:

$> brew install git-core git-flow    # (newer) Git stuff
$> brew install mkdocs               # (optional) install mkdocs
$> brew install pyenv pyenv-virtualenv direnv # see https://varrette.gforge.uni.lu/tutorials/pyenv.html
$> brew tap caskroom/cask            # install brew cask  -- see https://caskroom.github.io/
$> brew cask install virtualbox      # install virtualbox -- see https://www.virtualbox.org/
$> brew cask install vagrant         # install Vagrant    -- see https://www.vagrantup.com/downloads.html
$> brew cask install vagrant-manager # see http://vagrantmanager.com/
$> brew cask install docker          # install Docker -- https://docs.docker.com/engine/installation/mac/

Note: later on, you might wish to use the following shell function to update the software installed using Homebrew.

bup () {
    echo "Updating your [Homebrew] system"
    brew update
    brew upgrade
    brew cu
    brew cleanup
    brew cask cleanup
}

Linux (Debian / Ubuntu)

# Adapt the package names (and package manager) in case you are using another Linux distribution.
$> sudo apt-get update
$> sudo apt-get install git git-flow build-essential
$> sudo apt-get install rubygems virtualbox vagrant virtualbox-dkms

For Docker, choose your distribution from https://docs.docker.com/engine/installation/linux/ and follow the instructions. You need a reasonably new kernel version (3.10 or higher). Here are detailed instuctions per OS:

Windows

On Windows (10, 7/8 should also be OK) you should download and install the following tools:

The Git installation requires a few changes to the defaults, make sure the following are selected in the installer:

  • Select Components: Use a TrueType font in all console windows)
  • Adjusting your PATH environment: Use Git and optional Unix tools from the Windows Command Prompt
  • Configuring the line ending conversions: Checkout Windows-style, commit Unix-style line endings)
  • Configuring the terminal emulator to use with Git Bash: Use MinTTY (the default terminal of MSYS2)
  • Configuring extra options: Enable symbolic links

Please note that to clone a Git repository which contains symbolic links (symlinks), you must start a shell (Microsoft PowerShell in this example, but a Command Prompt - cmd.exe - or Git Bash shell should work out fine) with elevated (Administrator) privileges. This is required in order for git to be able to create symlinks on Windows:

  • Start Powershell:
    1. In the Windows Start menu, type PowerShell
    2. Normally PowerShell will appear as the first option on the top as Best match
    3. Right click on it and select "Run as administrator"

See also the instructions and screenshots provided on this tutorial.

Post-Installations checks

Git:

(Eventually) Make yourself known to Git

$> git config –-global user.name  "Firstname LastName"              # Adapt accordingly
$> git config –-global user.email "Firstname.LastName@domain.org"   # Adapt with your mail

Clone the tutorial repository on Github from a Terminal (Powershell as administrator under windows):

$> mkdir -p ~/git/github.com/ULHPC
# Clone reference git
$> cd ~/git/github.com/ULHPC
$> git clone https://github.com/ULHPC/tutorials.git

Vagrant

Ensure that vagrant is running and has the appropriate plugins from the command line

$> vagrant --version
Vagrant 2.1.1

Docker (only required for containers tutorials)

Launch the Docker app and then check that the Docker works:

$> docker info
Containers: 9
 Running: 0
 Paused: 0
 Stopped: 9
Images: 12
Server Version: 18.03.1-ce
[...]
  • Pull the docker containers we might need for the concerned tutorial
$> docker pull centos
  • Login onto you Docker hub account (take note of your Docker Hub ID and password).
    • With docker installed, run
$ docker login -u <your docker hub ID>

and enter your password.

Note that if the Docker installation fails, you can use http://play-with-docker.com/ to try Docker, but it won't work if all of us try it once! So use it only as a last resort, and it is up to you to use any important information (like the Docker hub account) inside it.

Mkdocs

It probably makes sense to install mkdocs to be able to generate locally the current documentation.

Follow for that the instructions provided on the ../rtfd.md.