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:
- Installation on the local machine
- 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:
- Prepare a repository for your presentation (this may already have been done by a colleague)
- Create a new VirtualBox VM for the course
- Clone the repository to your machine (your laptop, and the VM)
- Prepare a virtual machine for the course
- Install required software for the course
- Test the materials
- 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.
- Log in to GitHub
- In the upper right-hand corner of any page, click
+
and thenImport Repository
- Provide the URL of a previous IBioIC training course repository
- Choose an account or organisation to own the repository
- Choose a name for the repository (
YYYY-MM-DD-ibioic
works for us) - Specify that the repository should be public
- Click on
Begin Import
- You will receive an email informing you when the repository has been imported
- 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: