Setup Updated April 1, 2020


After installing Virtool, the server can be started by issuing the following command in the Virtool install directory.


Use ./run --help to see an overview of additional command line arguments Virtool can accept.

By default, the server listens at localhost:9950. When you visit this address for the first time, you will have to complete a one-time setup interface.

“Setup page overview”

This will allow you to configure the essential settings required for Virtool to run. Click the Setup button to begin.

Connect to a Proxy

If you connect to the internet through a proxy, you can configure it here.

You can skip this step if you don’t use a proxy.

“Successful proxy configuration

HTTPS proxies are not currently supported.

Connect to MongoDB

MongoDB must be installed and running before you can use Virtool.

Once MongoDB is ready, you can configure a connection to it using a MongoDB connection string and database name. When setup is complete, a new database will be created using the provided name.

MongoDB default placeholder parameters

The placeholder values can be used by clicking Connect without changing the form. You can also specify a different address, authentication, or authentication database for your connection by changing the connection string.

Virtool will return an error if there is already a database with the provided Database Name.

MongoDB alternate connection parameters

You will see something like the following when the connection is successful:

MongoDB successful connection


We highly recommend enabling authentication for MongoDB.

The MongoDB connection string is stored in plaintext in the application configuration file. Configure Virtool using environmental variables to keep your connection string safe.

Set Data Location

The data location is where Virtool stores bioinformatic data including uploaded Illumina libraries, imported sample data, and reference indexes. The path should be located on a storage device that offers good speed, capacity, and redundancy.

Paths beginning with / will be assumed to be absolute paths. All other paths will be interpreted relative to the Virtool installation directory.

Data path form with default placeholder value

By default the path will be set to data and will be created in the Virtool installation directory. This configuration should only be used for testing purposes. Use a path on a separate RAID volume or network attached storage (NAS) to store data securely.

Data path form with custom value

When the data path has been successfully configured, you should see something like this:

Data path configuration successfull

Errors will occur if:

  • the executing user does not have permission to write the data path
  • the data path already exists and is not empty

Set Watch Location

The primary method for making Illumina FASTQ files available to Virtool for sample creation is by uploading them through the web interface.

It is also possible to set a path accessible to the server that will be watched for new read files. Any FASTQ files dropped in this watch directory will be pulled into Virtool and made available for sample creation.

By default the data path will be set to watch and will be created in the Virtool installation directory.

Watch path form with default placeholder value

When the watch location has been successfully configured, you will see something like this:

Watch path configured successfully

Save and Restart

Once all setup sections have been completed, a summary will be displayed and a Save and Restart button will be be enabled.

Server setup summary

Clicking the button will apply all of the summarized actions and restart the server. You can login for the first time with the user profile you created during setup.

Server restarting after setup

Manual Setup

It is possible to configure Virtool without completing the graphical setup process.

Passing the --no-setup argument when running Virtool will skip the setup process and use default configuration values or values from manual configuration sources.

Add First User

Once the server has been setup, you have to create an initial user. This user will be automatically given an administrative role.

This form will appear if no users are present in the configured database:

Empty user form

Fill out the form with an administrator username and password and click Create User:

Filled out user form

The Virtool application should load and automatically log in as the new user:

First user successfully created


We strongly recommend not making the account a generic adminstrative account.

Doing so defeats Virtool’s built-in auditing, which is designed in accordance with ISO 17025:2005. Each account should correspond to an individual user.