EPI2ME Labs Installation

The following guide illustrates installation and use of EPI2ME Labs for running workflows and tutorials.

The EPI2ME Labs environment runs in a Docker container in order to provide an isolated and resettable environment. It can be controlled using the EPI2ME Labs application. The instructions below will install both of these tools onto your system. For the most part, these instructions simply reiterate the documentation from the linked resources.

Windows 10 installation

Windows 11 support is untested, but is expected to work much the same as Windows 10

For the workflows in EPI2ME Labs to work you will require Windows build 18362.1049 or higher. To check this: Click Start > search ‘Windows update settings’ > at the bottom select ‘OS Build info’. If your build is earlier you may have Windows updates available at the top of this settings menu which you can install. Our Nextflow on Windows guide provides a second method to set up an environment to run our Nextflow workflows on old versions of Microsoft Windows. Users having issues with the method presented here or wanting to run our workflows from Windows cmd line may wish to read the alternative instructions.

Our downloads page contains a link to the latest EPI2ME Labs installer. The installer will guide users through the installation; it should be noted that during the install your computer may restart.

We are now ready to install Docker Desktop on Windows following Docker’s instructions. Follow the link to download the installer for the WSL2 Backend variant. When the download is finished launch the installer and be sure that the checkbox to install Windows components for WSL2 is checked as in the below when given the option:

When the installation is complete you may be asked to logout of Windows. Promptly log back in and launch Docker Desktop from the desktop icon. The application will start and walk you through some basics. Follow these at you leisure or simply skip to the opening Powershell and running the command:

docker run -d -p 80:80 docker/getting-started

This will likely pop up a Windows Security Alert which you should allow:

Within the Docker Desktop application window you should see a new entry:

The Delete icon can be safely clicked to remove the running Docker container.

In Docker Desktop settings check that under resources WSL integration Ubuntu is enabled.

You’re now ready to use EPI2ME Labs type epi2melabs in the Windows search bar to find and open the application:

Resource Limits for Docker on Windows

Resource limits for Docker on Windows will be managed by Windows. You need to create a new or edit the existing file - C:/Users/<USERNAME>/.wslconfig.

Copy and paste the following and adjust. We recommend setting the Memory limit to at least 8G and the CPUs to one or two less than the maximum value for your system

[wsl2]
memory=8GB 
processors=4
localhostForwarding=true 

MacOS installation

A link to the current version of the EPI2ME Labs can be found on our Downloads page. The application is provided as a standard MacOS disk image (.dmg file), the contents of which can be unpacked into a users Applications directory in the usual manner.

MacOS users are encouraged to follow the installation instruction for Docker Desktop found on the Docker Website.

To use the workflow launching features of EPI2ME Labs, Java and must be installed. Java can be installed by following the links from: https://www.oracle.com/java/technologies/downloads/. For macs with M1 processers the Arm 64 installer is required: https://download.oracle.com/java/18/latest/jdk-18_macos-aarch64_bin.dmg. For older, Intel Macs the x64 installer should be downloaded instead: https://download.oracle.com/java/18/latest/jdk-18_macos-x64_bin.dmg

Resource Limits for Docker Desktop on MacOS

By default Docker Desktop sets fairly conservative resource limits for itself, you may wish to change these in the Docker Desktop settings pane. We recommend setting the Memory limit to at least 8Gb (some EPI2ME Labs tutorials may require more as indicated in their introductions) and the CPUs to one or two less than the maximum value for your system.

GridIon/PromethION/Ubuntu install

Docker is not installed by default on older GridION and PromethION devices. If an updated MinKNOW has been installed then Docker should be present. We advise users to first try running:

docker run hello-world

from a terminal window as in the instructions below to check the status of any Docker installation. If this command fails, ensure that MinKNOW is up to date.

Installing docker

This step should not be required on GridION and PromethION devices with up-to-date operating system installations.

To install Docker without an up-to-date MinKNOW install follow the instructions below.

1. Click on the Search your computer button.

2. Search for “terminal”, and click on the Terminal application:

A terminal window will open:

3. Run the Docker installation command (you can copy and paste this into the terminal window and press Enter):

   sudo apt update
   sudo apt install docker.io
   sudo usermod -aG docker <username>
   

   where <username> should be replaced with your computer username.
4. Close your terminal window.
5. Log out of your GridION and log back in again.
6. Open a new terminal window.
7. To test docker is working correctly, run docker run hello-world

Installing Nextflow

Installation of the software on Oxford Nanopore Technologies’ sequencing device can be performed using the command:

sudo apt install ont-nextflow

This will install a Java runtime, Nextflow, and Docker. If docker has not already been configured the command below can be used to provide user access to the docker services. Please logout of your computer after this command has been typed.

sudo usermod -aG docker $USER

When installing Nexflow using the following please ensure that Nextflow version >= 20.07.1 is installed.

For hardware running Ubuntu (with is not an Oxford Nanopore Technologies sequencing device) the following should suffice to install nextflow in order to run workflows from within EPI2ME Labs.

1. Install a Java runtime environment (JRE):

   sudo apt install default-jre

2. Download and install Nextflow may be downloaded from https://www.nextflow.io:

   curl -s https://get.nextflow.io | bash

   This will place a nextflow binary in the current working directory, you may wish to move this to a location where it is always accessible, e.g:

   sudo mv nextflow /usr/local/bin

Installing EPI2ME Labs on GridION and PromethION

EPI2ME Labs is most easily installed:

1. Copy and paste the following into the terminal window and press Enter:

   sudo apt update
   sudo apt install ont-epi2melabs
   

2. Click on the Search your computer icon, and search for “EPI2ME”. Then click on the EPI2ME-Labs Server Control icon. This will start EPI2ME Labs.

Reinstallation of EPI2ME Labs on GridION and PromethION

In the event you wish to reinstall EPI2ME Labs on GridION and PromethION it is vital to run purge to remove the original version of EPI2ME Labs and its associated configuration files.

1. Copy and paste the following into the terminal window and press Enter:

   sudo apt purge ont-epi2melabs
   sudo apt autoremove
   

2. Copy and paste the following into the terminal window and press Enter:

   sudo apt update
   sudo apt install ont-epi2melabs
   

   The first step removes EPI2ME Labs and any associated configuration files and dependencies that are only required by EPI2ME Labs. The second step reinstalls the EPI2ME Labs.