EPI2ME Labs Installation

December 05, 2022
5 min read
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.

Setup required
'Setup required' panel when dependencies are missing

  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.

    Install WSL
    Installing WSL via the app

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

    Downloading ubuntu
    WSL: Downloading Ubuntu

    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.

    Installing ubuntu
    WSL: Installing Ubuntu

    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.

    Choosing username ubuntu
    WSL: Choosing user credentials

    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

    Install java
    Installing Java via the app

    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.

    Install docker
    How to install Docker

    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.

Docker WSL integration
Enable Docker for all WSL distros

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.

Docker autostart
Start Docker whenever you start your machine

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.

Docker resource
Docker resource limits

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.

Search computer 1
Search for terminal

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

Search computer 2
Search for terminal

A terminal window will open:

Terminal window
Terminal window

  1. 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.
  2. Close your terminal window.
  3. Log out of your system, and log back in again.
  4. Open a new terminal window.
  5. To test Docker is working correctly, run docker run hello-world

Docker hello
Docker hello world


Share

Table Of Contents

1
Windows 10 installer
2
MacOS package
3
Debian-based Linux package
4
Installation
5
Resource Limits
6
Installing Docker on Linux without Docker Desktop

Quick Links

TutorialsWorkflowsOpen DataContact

Social Media

© 2020 - 2023 Oxford Nanopore Technologies plc. All rights reserved. Registered Office: Gosling Building, Edmund Halley Road, Oxford Science Park, OX4 4DQ, UK | Registered No. 05386273 | VAT No 336942382. Oxford Nanopore Technologies, the Wheel icon, EPI2ME, Flongle, GridION, Metrichor, MinION, MinIT, MinKNOW, Plongle, PromethION, SmidgION, Ubik and VolTRAX are registered trademarks of Oxford Nanopore Technologies plc in various countries. Oxford Nanopore Technologies products are not intended for use for health assessment or to diagnose, treat, mitigate, cure, or prevent any disease or condition.