Installation for Tutors

This document will describe the process for setting up and testing course materials, in preparation for delivery to a class.

Two setups are described:

  1. Installation on the local machine
  2. Installation on a Linux virtual machine

We prefer that students install materials on their own laptops for the course, as the software and learning materials will then persist and be usable/re-usable after the course itself. The virtual machine approach is a “Plan B” backup option that should be workable on any machine, and is intended as the fallback in case of severe installation problems.

Important

Each new course presentation should be prepared in its own repository. Following the practice of The Carpentries we have adopted the convention of naming the course repository by date as YYYY-MM-DD-ibioic.

The process of installation for course preparation for tutors is as follows:

  1. Prepare a repository for your presentation (this may already have been done by a colleague)
  2. Create a new VirtualBox VM for the course
  3. Clone the repository to your machine (your laptop, and the VM)
  4. Prepare a virtual machine for the course
  5. Install required software for the course
  6. Test the materials
  7. Upload the working VM to `Zenodo`_

1. Prepare a new repository

Note

If one of your colleagues has already created/imported a repository for your presentation, you can skip this part.

When creating a new repository for a new course presentation, please use the GitHub Importer and provide an existing repository URL to build from, rather than forking an existing repository.

  1. Log in to GitHub
  2. In the upper right-hand corner of any page, click + and then Import Repository
  3. Provide the URL of a previous IBioIC training course repository
  4. Choose an account or organisation to own the repository
  5. Choose a name for the repository (YYYY-MM-DD-ibioic works for us)
  6. Specify that the repository should be public
  7. Click on Begin Import
  8. You will receive an email informing you when the repository has been imported
  9. Inform the other tutors about the repository and/or invite them as collaborators

2. Create a new VirtualBox VM

If it is not already available, download and install VirtualBox on your machine. This is a free-to-use general-purpose full virtualizer for x86 hardware, capable of running a virtual machine for use by students on the course.

Tip

The virtual machine for the course may be large, so can be prepared for download by the students well in advance,and include a working git installation, so the student can pull an up-to-date copy of the course materials during the course. What is important is that the supporting software are available and can be run on the student’s machine

Once VirtualBox is installed, create a new Ubuntu VM with the same name as your repository for the course presentation.

3. Clone the repository to your machine

Attention

These instructions should be followed to reproduce the repository and required software on both the VirtualBox VM prepared above, and on your own machine

Warning

If you do not have a working copy of git installed on your machine, install one now. This will be required to maintain and publish your repository materials.

You should clone the repository to your own machine, with the command:

git clone <REPOSITORY URL>

where <REPOSITORY URL> is the repository you have just imported.

Finally, change directory to the root of the new repository.

4. Prepare a conda virtual machine for the course

For ease of installation and consistency, we install as much as is practical using the Anaconda environment. This is cross-platform on Windows, macOS and Linux, and provides several essential components for the course, such as Python and the common Jupyter notebook interface that will be used.

Note

If you do not already have Anaconda installed on your system, please follow the instructions:

Create a new Anaconda environment

With Anaconda installed, create a new environment with:

conda create --name <ENVIRONMENT_NAME> python=3.6

Accept all the installation options presented.

Tip

We recommend naming your environment after your repository, using something like 2018-03-06-ibioic as your <ENVIRONMENT_NAME>

Then, activate the environment with

source activate <EVIRONMENT_NAME>

You should see your terminal prompt change to include the environment name. This is a reminder that you are working within the specific Anaconda environment for the course materials.

Some tools are useful to us as tutors, for preparing and managing the course materials. These are specified in the file requirements_tutors.txt, and should be installed now with the command:

pip install -r requirements_tutors.txt

5. Install required software for the course

We prefer that students use their own laptops for course delivery, and we aim to match the students’ installation experience here, as closely as possible.

Python dependencies

Although we could install most of the python requirements with Anaconda, some of the packages are not available on Windows with this approach, so we install using pip instead:

pip install -r requirements_students.txt

Third-party software

BLAST and MUSCLE do not require JAVA, and can be set up independently:

ARTEMIS, JALVIEW and JMOL require the JAVA VM, so JAVA must be installed first:

6. Test the materials

7. Upload the VM to `Zenodo`_