This document describes how to install the IRIDA web interface. We assume that you have completed installing and configuring Galaxy.

The IRIDA platform currently consists of three, separate components:

  1. The web interfaces: User interface and API,
  2. Galaxy, and
  3. Command-line clients.

The IRIDA Web interfaces are intended to be deployed in a Servlet container, supporting Servlet 3.0 or higher. You can download IRIDA as a pre-packaged WAR file at https://irida.corefacility.ca/downloads/webapp/irida-latest.war.

Prerequisites

The following prerequisites are required for running the IRIDA web interfaces:

Prerequisite install instructions

We provide some instructions for installing and setting up your production environment. If you are comfortable installing and configuring a servlet container, or if your production environment has already been configured, you can safely skip this section.

Deploying IRIDA

Deploying IRIDA mainly involves deploying the WAR file into your Servlet container, but does also require some configuration outside of your Servlet container.

Servlet Container Configuration

Two environment variables needs to be set in your Servlet container for IRIDA to function correctly: spring.profiles.active=prod, and dandelion.profile.active=prod.

You can adjust these variables in Tomcat by editing (depending on your distribution) /etc/tomcat/tomcat.conf (CentOS) or /etc/default/tomcat7 (Ubuntu), and finding the JAVA_OPTS variable and setting the variables as shown below:

JAVA_OPTS="-Dspring.profiles.active=prod -Ddandelion.profile.active=prod"

Core Configuration

All IRIDA configuration files are stored in /etc/irida/. The main IRIDA configuration file should be written to /etc/irida/irida.conf. irida.conf is a plain, Java properties file (so a key-value pair file). You can download the file from config/irida.conf, or you can find an example below:

##### The filesystem location where files managed by irida are stored. The platform
##### will *NOT* automatically make this directory, so it must exist before you
##### start any instance of the platform.
sequence.file.base.directory=/opt/irida/data/sequence
reference.file.base.directory=/opt/irida/data/reference
output.file.base.directory=/opt/irida/data/output

##### Set the max upload size (in bytes). If left unconfigured, the max upload
##### size is unlimited (or limited by the container hosting IRIDA).
# file.upload.max_size=

##### Set number of threads for FASTQC and file post-processsing.  The max size
##### should not be more than the number of jdbc threads.
file.processing.core.size=4
file.processing.max.size=8
file.processing.queue.capacity=512


##### The database-specific settings. Several examples of how to specify a
##### Hibernate driver are listed below (but commented out).

## MySQL (or MariaDB)
jdbc.driver=com.mysql.jdbc.Driver
hibernate.dialect=org.hibernate.dialect.MySQL5Dialect

## Database location (you may need to use a different string for different
## database vendors).
jdbc.url=jdbc:mysql://localhost:3306/irida_test

## Connection settings:
jdbc.username=test
jdbc.password=test

## Configuring Liquibase to execute a schema update. Should only make changes to
## the database when executing the first time, or when upgrading.
liquibase.update.database.schema=true

## Configure Hibernate to execute a schema construction. WARNING: do not use this
## at the same time as the Liquibase schema update. Liquibase will *not* execute
## if this value is set, warnings will be produced in the log. These settings should
## only be used in a development environment (**not** production).
hibernate.hbm2ddl.auto=
hibernate.hbm2ddl.import_files=

## Configure Hibernate to show SQL in the log file. You *probably* don't want
## to enable this, but could be useful for debugging.
hibernate.show_sql=false

## Connection Pool settings:
jdbc.pool.initialSize=10
jdbc.pool.maxActive=20
jdbc.pool.testOnBorrow=true
jdbc.pool.testOnReturn=true
jdbc.pool.testWhileIdle=true

## Configure the JDBC library to use this query to verify that a managed
## connection is still valid. This may need to change, depending on your database vendor.
jdbc.pool.validationQuery=select 1

jdbc.pool.maxWait=10000
jdbc.pool.removeAbandoned=true
jdbc.pool.logAbandoned=true
jdbc.pool.removeAbandonedTimeout=60
jdbc.pool.maxIdle=10

###############################################################################
# Execution Manager configuration Galaxy. This is how IRIDA should connect to #
# the internally managed instance of Galaxy for executing workflows.          #
###############################################################################

# The URL for the Galaxy execution manager
galaxy.execution.url=http://localhost/

# The API key of an account to run workflows in Galaxy.
# This does not have to be an administrator account.
galaxy.execution.apiKey=xxxx

# The email address of an account to run workflows in Galaxy
galaxy.execution.email=user@localhost

# The data storage method for uploading data into a Galaxy execution manager.
galaxy.execution.dataStorage=local

##################################
# Workflow configuration options #
##################################

# The timeout (in seconds) for uploading files to Galaxy for execution
# Increase this value if uploading files to Galaxy is timing out.
#galaxy.library.upload.timeout=300

# The polling time (in seconds) for checking if files have been uploaded to Galaxy
# This value should not be greater than $galaxy.library.upload.timeout
#galaxy.library.upload.polling.time=5

# Number of threads used to wait for completion of uploading files.
#galaxy.library.upload.threads=1

# Maximum number of workflows IRIDA will schedule to run at the same time
irida.workflow.max-running=4

##################################
# Analysis configuration options #
##################################

# The number days before intermediate files for an analysis get cleaned up.
# That is, the number of days before files in Galaxy get deleted for the analysis.
# Leave commented out for no cleanup.
# This value can be fractional representing a fraction of a day (e.g. 0.5 for half a day).
#irida.analysis.cleanup.days=

#################################
# Scheduled Task  configuration #
#################################
#Cron string for how often the email subscriptions are sent out.
#Format: sec min hrs dom mon dow
irida.scheduled.subscription.cron=0 0 0 * * *
irida.scheduled.threads=2

#################################
# NCBI SRA Export configuration #
#################################
#Host to upload ncbi exports
ncbi.upload.host=localhost
#FTP Username and password for bulk SRA uploads
ncbi.upload.user=test
ncbi.upload.password=password
#base directory in which to create SRA submissions
ncbi.upload.baseDirectory=tmp
#port for ftp upload
ncbi.upload.port=21
#Default namespace to preface file identifiers
ncbi.upload.namespace=IRIDA

If this file does not exist, the platform will use internal configuration values. The internal configuration values point at a local instance of the database server. The likelihood of the internal configuration values correspond to your production environment is alarmingly low (or at least, should be).

The main configuration parameters you will need to change are:

  1. Directories to store files managed by IRIDA:
    • sequence.file.base.directory=/opt/irida/data/sequence - Sequence files managed by IRIDA.
    • reference.file.base.directory=/opt/irida/data/reference - Reference files assigned to projects in IRIDA.
    • output.file.base.directory=/opt/irida/data/output - Results of analysis pipelines.
  2. Threads used for file processing (FastQC, GZip, etc):
    • file.processing.core.size=4 - The initial number of threads available for file processing.
    • file.processing.max.size=8 - The maximum number of available threads for file processing. This number should not exceed the configured maximum number of JDBC threads.
    • file.processing.queue.capacity=512 - The maximum number of file processing jobs that can be queued.
  3. Database connection information:
    • jdbc.url=jdbc:mysql://localhost:3306/irida_test
    • jdbc.username=test
    • jdbc.password=test
  4. Galaxy connection information for executing pipelines:
    • galaxy.execution.url=http://localhost/
    • galaxy.execution.apiKey=xxxx
    • galaxy.execution.email=user@localhost
    • irida.workflow.max-running=4 - The maximum number of running workflows. For larger installations this number can be increased.
  5. NCBI SRA export configuration - An SRA bulk upload user account must be created with NCBI to allow automated SRA uploads. See NCBI SRA Handbook for details.
    • ncbi.upload.host - FTP host to upload ncbi exports
    • ncbi.upload.user - FTP Username
    • ncbi.upload.password - FTP password
    • ncbi.upload.baseDirectory - base directory in which to create SRA submissions
    • ncbi.upload.namespace - Prefix for file upload identifiers to NCBI. The namespace is used to guarantee upload IDs are unique. This configuration option is used as a placeholder and may still be set by the user.

Web Configuration

The IRIDA platform also looks for a web application configuration file at /etc/irida/web.conf. Similar to the irida.conf file, this file is a plain Java configuration file. The properties in this file will be used to configure parameters of the web application component of the IRIDA platform. You can download the file from config/web.conf, or you can find an example below:

# The externally visible URL for accessing this instance of IRIDA. This key is
# used by the e-mailer when sending out e-mail notifications (password resets,
# for example) and embeds this URL directly in the body of the e-mail.
server.base.url=http://localhost:8080

# Mail server configuration settings
mail.server.host=your-mail-server.local
mail.server.protocol=smtp
mail.server.email=irida@your-mail-server.local
mail.server.username=IRIDA Platform

# Location of the IRIDA Platform updates file
# updates.file=/etc/irida/updates.md

# The title and link for an external help resource. Uncomment these
# and modify to have your own link rendered in the 'Help' menu. If these
# are left commented out, no link appears under the 'Help' menu.
# help.page.title=Your Help Page Title
# help.page.url=http://www.example.org/help

# The e-mail address for contacting an administrator for help. Uncomment
# this and modify to have your own e-mail address rendered in the 'Help' menu.
# If this is left commented out, no contact e-mail appears in the 'Help' menu.
# help.contact.email=you@example.org

If this file does not exist the platform will use internal configuration values which will probably not correspond to your production environment.

The mail.server.* configuration parameters will need to correspond to a configured mail server, such as Postfix. This will be used by IRIDA to send email notifications to users on the creation of an account or on password resets.

Analytics

The IRIDA platform supports web analytics. Include the analytic snippet inside a file in /etc/irida/analytics/. The snippet will be injected into the page.

E.g. In /etc/irida/analytics/google-analytics.html.

<script type="text/javascript">

  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', 'UA-XXXXX-X']);
  _gaq.push(['_trackPageview']);

  (function() {
    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
    ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  })();

</script>

Deploy the WAR File

Once you have adjusted the configuration files to your environment, you can deploy the WAR file to your servlet container.

You can download the WAR file from: https://irida.corefacility.ca/downloads/webapp/irida-latest.war

Tomcat’s deployment directory is typically some variation of /var/lib/tomcat/webapps/. Deploying the WAR file in Tomcat is as simple as moving the WAR file you downloaded into that directory.

On startup, IRIDA will:

  1. Automatically prepare the database on your system (using Liquibase) using the database connection details you specified in Core Configuration.
  2. Install any internally configured workflows.
  3. Configure the connection to Galaxy.

If IRIDA has successfully been deployed, you should be able to use your web browser to navigate to http://localhost:8080/irida-latest/ (assuming you’re deploying to the local machine, and also assuming that you’ve left the WAR file named irida-latest.war).

Logging in for the first time

The first time IRIDA is run, it will add a default administrator user account to the database. Launch your web browser and navigate to the context where you’ve deployed IRIDA.

If everything has been configured correctly, you should see the IRIDA log-in page:

IRIDA Log in page

The default administrator username and password are:

You will be required to change the password the first time you log-in with these credentials.

Once you’ve logged in for the first time, you will probably want to create some user accounts. User account creation is outlined in our Administrative User Guide.