EPI2ME Labs Installation

Installing bioinformatics software can be notoriously difficult for the uninitiated. EPI2ME Labs aims to allow the analysis of anything, anywhere, by anyone. We have simplified the installation and use of bioinformatics tools and resources for Oxford Nanopore sequencing applications.

This page is intended to complement the documentation provided inside the app for guiding the user through the installation process.

Windows 10 installer

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 details on installing EPI2ME Labs dependencies on older Windows versions. Users having issues with the automated setup within EPI2ME Labs may wish to read these alternative instructions.

The Downloads page contains a link to the latest EPI2ME Labs installer. Download and run it to launch the app.

MacOS package

Note: Not all of our bioinformatics workflows are currently fully supported on Apple devices with ARM processors — we aim to resolve this in early 2023.

A link to the current version of EPI2ME Labs can be found on our downloads page. The application is provided as a standard MacOS package (.pkg) file and will install into the usual /Applications location.

Debian-based Linux package

A link to a .deb package of the current version of EPI2ME Labs can be found on our Downloads page. After the download, the application can be installed via the GUI Software Center (on Ubuntu; simply double-click the .deb file) or from the command line (using either sudo dpkg -i /path/to/deb/file or sudo apt install /path/to/deb/file).

The EPI2ME Labs version 4 package is not currently available from the Oxford Nanopore Technologies Debian package repository.

Installation

EPI2ME Labs uses Nextflow and Docker to run bioinformatics workflows from a desktop application. It was designed to be as easy to install and set up as possible. Thus, it can install most of the required dependencies (Java, Nextflow) automatically and provides guided installation for other components (Windows Subsystem for Linux (WSL), Docker).

In this section we will run through the installation of software dependencies for EPI2ME Labs version 4.0.0 and onwards. The application provides a guided installation for its dependencies and many steps are automated. In more complicated installation environments the application will provide additional notes and resources to help you resolve any issues that arise.

To start, first obtain the installer package from our Downloads page. After running the installer and opening the application, the program will look for the required dependencies and show an “Additional setup is required” panel in case one or more are missing. If you see the panel, click on it to finish the setup.

1. Installing Windows Subsystem for Linux via the application [Windows only]

   If the app finds that WSL is not installed on your system, it will show you a dialog box with extra information and a button for installing it.

   

   After clicking the button and granting permissions, a terminal window should pop up and download WSL for you.

   

   Once this has finished, please restart your computer. After the restart, another terminal window will open and complete the installation. This may take some time.

   

   At some point, the terminal will ask you to provide a username and password for the Ubuntu distribution installed by WSL. In some cases the terminal window running the installation might “get stuck” and fail to ask for the username. If it is still reading Installing, this may take a few minutes... after 5+ minutes, click into the window and press Enter to update the display.

   

   After providing username and password, you can close this window. Note that the credentials you choose here do not need to be the same as you Windows username and password, but you may use these if desired.

   In EPI2ME Labs the WSL check should now pass and we can continue with the other dependencies.

2. Installing Java and Nextflow via the application

   

   These two need no intervention by the user and can be installed by simply clicking the Install via Labs button. They should install quickly. On Windows (and depending on your particular networking setup), however, WSL might not be able to reach the internet. If this is the case, please go back to the WSL install dialogue box and read the section on networking and wsl-vpnkit.

   After Java is installed and the check passes, carry on to Nextflow and again click the button to install it.

3. Installing Docker

   Docker is preinstalled on GridION and PromethION devices. If you find that Docker is missing when installing EPI2ME Labs on one of these machines, please contact customer support.

   Unfortunately, EPI2ME Labs cannot fully automate the install of Docker The easiest way of installing Docker is via Docker Desktop. Follow the instructions on the dialog box in EPI2ME Labs in order to set it up correctly.

   

   If you are on Linux and want to install Docker without Docker Desktop, please refer to the instructions at the bottom of this page.

Once all checks pass, the “Additional setup” dialog boxes will disappear and the EPI2ME Labs application will be ready for running bioinformatics analyses!

Additional setup for Docker Desktop

After installing Docker Desktop, we need to make sure that it makes Docker available to all WSL distros and that it starts automatically whenever you reboot your machine.

To this end, open the Settings page in Docker Desktop and navigate to “Resources” and “WSL Integration”. Tick all WSL distros as shown below.

Then, in the General settings tab, tick “Start Docker Desktop when you log in”. You can also scroll down and untick “Open Docker Dashboard at startup” if you want the app to start in the background. Click “Apply & restart” so that the changes take effect.

Resource Limits

Computational resources available to Docker are restricted. You can change these limits in order to fully utilise your computer.

Windows

Resource limits on Windows will be equivalent to the limits for WSL. You need to create a new file at C:\Users\<USERNAME>\.wslconfig (or edit it if it already exists).

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 and Linux

In MacOS and Linux, resources can be managed in the Preferences section of Docker Desktop directly. We recommend setting the memory limit to at least 8Gb if more RAM is available and the CPUs to one or two less than the maximum value for your system.

Installing Docker on Linux without Docker Desktop

The use of EPI2ME Labs on Linux does not require the installation of the Docker Desktop application, only docker. For a more minimal Docker installation, follow the instructions below. We recommend this method only for users comfortable with managing a docker installation from the command line.

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 system, and log back in again.
6. Open a new terminal window.
7. To test Docker is working correctly, run docker run hello-world