Installation Updated February 5, 2020

System Requirements

We recommend the following minimum specifications for running a Virtool server:

  • Linux operating system
  • 32 GB RAM
  • 1 TB fast storage
  • 1 Gb network connection

Higher CPU clock speeds and core counts will allow more operations to be run in parallel.

Browsers

Virtool works best in modern browsers including Chrome, Firefox, Safari, and Edge. Internet Explorer is not supported.

Install the Server

Download the latest Virtool release from the Virtool website and unpack the downloaded archive.

tar -xvf virtool.tar.gz

Move the unpacked directory to your installation location:

mv virtool /opt

Start Virtool by executing the run file:

./run

Run as a Service

Virtool can be configured to run as a service on your Linux host using systemd. These instructions make the following assumptions:

  • You run Virtool using a dedicated user called virtool.
  • Virtool is installed at /home/virtool/app.

Create a new service unit file for Virtool at /etc/systemd/system/virtoold.service:

[Unit]
Description=A application server for NGS-based virus diagnostics.
Documentation=https://www.virtool.ca/docs
Requires=mongod.service network.target
After=mongod.service network.target

[Service]
Type=simple
User=virtool
WorkingDirectory=/home/virtool/app
ExecStart=/home/virtool/app/run

[Install]
WantedBy=mongod.service network.target mnt-array0.mount

Reload the systemd configuration:

sudo systemctl daemon-reload

The service configuration ensures that Virtool doesn’t start until mongod and networking services have started.

RedHat provides detailed information about systemd unit files. See Creating and Modifying systemd Unit Files.

Start the Service

To start Virtool using systemd, issue the following command:

sudo systemctl start virtoold.service

You can check if Virtool is running with the following command:

sudo systemctl status virtoold.service

The service status should look something like this if Virtool is running:

● virtoold.service - A application server for NGS-based virus diagnostics.
   Loaded: loaded (/etc/systemd/system/virtoold.service; enabled; vendor preset: enabled)
   Active: active (running) since Fri 2020-01-31 09:11:50 PST; 1h 6min ago
     Docs: https://www.virtool.ca/docs
 Main PID: 1523 (run)
    Tasks: 203 (limit: 7372)
   CGroup: /system.slice/virtoold.service
           ├─ 1523 /home/virtool/app/run
           ├─29957 /home/virtool/app/run
           ├─30106 python /usr/local/bin/spades.py -t 14 -m 60 -s /mnt/array0/virtool/data/samples/uaofeeaw/analysis/nqy9xo0n/unmapped_hosts.fq -o /tmp/tmplojfnvz9 -k 21,33,55,75
           ├─32037 /home/virtool/app/run
           └─32194 /opt/spades/bin/spades /tmp/tmplojfnvz9/K21/configs/config.info

Stop the Service

The service can be stopped using the following command:

sudo systemctl stop virtoold.service

You can check if the Virtool service has stopped using the status subcommand:

sudo systemctl status virtoold.service

Run on System Start

The provided service file allows Virtool to be run on system start.

Enable the virtoold.service to make it start when the system is initializing:

sudo systemctl enable virtoold.service

This can be undone by disabling the service:

sudo systemctl disable virtoold.service

MongoDB

Virtool uses MongoDB v3.6.0+ as a database service. You will have to get MongoDB running before starting Virtool. We highly recommend installing and updating MongoDB through your Linux package manager.

The MongoDB documentation provides step-by-step instructions for installing MongoDB on common Linux distributions:

Once you have installed MongoDB, ensure it is running by issuing the following command:

sudo systemctl status mongod.service

You will receive an output similar to the following if MongoDB is running:

● mongod.service - High-performance, schema-free document-oriented database
   Loaded: loaded (/etc/systemd/system/mongod.service; disabled; vendor preset: enabled)
   Active: active (running) since Fri 2017-04-21 15:55:59 PDT; 2s ago
 Main PID: 11844 (mongod)
    Tasks: 14
   Memory: 31.1M
      CPU: 95ms
   CGroup: /system.slice/mongod.service
           └─11844 /usr/bin/mongod --quiet --config /etc/mongod.conf

External Software

Virtool relies on a number of common bioinformatics programs. These should be available in your PATH so Virtool can find them. You will encounter errors if these programs are not available.

Name Version Purpose
Skewer 0.2.2 Read trimming and quality control
FastQC v0.11.5 Calculating quality metrics for sample libraries
Bowtie2 2.3.2 High-throughput read alignment
SPAdes v3.8.1 De novo assembly
HMMER 3.1b2 Motif detection