Instructions for using docker in Linux

The phylogenetics practical uses Docker, which means the long list of featured apps are pre-installed in one location and can be re-used, for example in your lab projects. However, there is some set up required. These instructions help explain how to set up on Ubuntu or Debian Linux.

(If these instructions don't work for you, you may have to fall back on installing the apps using the commands implied by the Dockerfile. Instructions for using docker in MacOS are here. If you are using a Windows machine, you will have to do your own research. Please report back any tips on this.)

NB: running Docker requires sudo permissions.

These instructions are courtesy of Nicolas Arning. 

First, run the following commands in a terminal to update the apt-get installer and install core utilities

sudo apt-get update

sudo apt-get install apt-transport-https ca-certificates curl gnupg-agent software-properties-common

Depending on your linux version type one of

curl -fsSL https://download.docker.com/linux/debian/gpg | sudo apt-key add -

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -

Followed by

sudo apt-key fingerprint 0EBFCD88

Again, depending on your linux version type one of

sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/debian $(lsb_release -cs) stable"

sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"

Install docker with the command

sudo apt-get install docker-ce docker-ce-cli containerd.io

Next activate the graphical interface by executing

xhost local:root

Finally, run the Docker container as follows:

sudo docker run -v $WDIR:/home -e DISPLAY=$DISPLAY -it --rm --env DISPLAY=unix$DISPLAY  -v /tmp/.X11-unix:/tmp/.X11-unix -v $XAUTH:/root/.Xauthority  --name practical dannywilson/teaching-phylogenetics:march2020

If that all went according to plan, you're ready to start the tutorial.

Instructions for using docker in MacOS

The phylogenetics practical now uses Docker, which means the long list of featured apps are pre-installed in one location and can be re-used, for example in your lab projects. However, there is some set up required. These instructions explain how to set up on MacOS 10.13 and higher. (If you've used Docker before, these additional steps might be new to you - they are required to run window-driven apps in Docker on a Mac, rather than the usual command line utilities.)

(The practical is designed and tested for Mac based on the machines available to the HDS DTC. If instead you are using a Linux machine, first try the Linux instructions here, and you can't get it to work, you may have to fall back on installing the apps using the commands implied by the Dockerfile. If you are using a Windows machine, you will have to do your own research. Please report back any tips on this.)

NB: these instructions require a log out-log in step, so you will need to save any other work that you have open before starting. Total installation time is about 10-15 minutes.

These instructions are courtesy of an online tutorial I found. They will walk you through installation of:

• Docker Desktop for Mac
• The network utility socat
• The windowing system Xquartz
• The package manager Homebrew

Docker Desktop for Mac 10.15 and above

Download for Macs running Catalina (10.15) or above with Intel chips here and Apple chips here. It's self-explanatory but if you need instructions visit https://hub.docker.com/editions/community/docker-ce-desktop-mac

The key step is to raise the default limit on system memory that docker can use. Otherwise apps in the tutorial will be killed. To do this, after installation, run Docker by clicking the whale icon. Once Docker has started, there will be a static icon in the menu bar. From this menu, select Preferences ... then Resources on the left hand list. The Resources panel allows you to increase the maximum CPUs, Memory and and Swap that docker can use. You will need above 2GB Memory. I suggest you increase memory to just below the maximum (e.g. 7.5GB on my machine), which should be fine if you don't use other memory-hungry apps while running the tutorial. When finished, click the button "Apply & Restart".

Homebrew

This is required for installation of socat and Xquartz. If you already use homebrew, skip this step.

At the Terminal, type (with no line break)

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

The final step of homebrew installations often appear to have frozen, so some patience is required. It may be necessary to add brew to your command line search path, e.g. export PATH=$PATH:/opt/homebrew/bin

Socat

In the same Terminal session, once homebrew installation is complete, type

brew install socat

Xquartz

This time, type

brew update && brew install --cask xquartz

Log out and then log in again

If you forget this step, the following won't work. You need to log out of your entire session (from the Apple Menu, Log Out or failing that, Restart).

Launch socat and Xquartz

The last step before starting the tutorial is to launch socat and Xquartz. Xquartz provides windows for apps running in docker, while socat allows docker to talk to Xquartz.

In the Terminal, type

socat TCP-LISTEN:6000,reuseaddr,fork UNIX-CLIENT:\"$DISPLAY\" &

If a 'Security' tab appears, tick the 'Allow connections from network clients' box.

Then launch Xquartz with

open -a Xquartz

If that all went according to plan, you're ready to start the tutorial.