IRIDA Documentation

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://github.com/phac-nml/irida/releases.

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 irida.db.profile=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 -Dirida.db.profile=prod"

The irida.db.profile=prod option sets a number of recommended database settings for IRIDA such as JDBC, Hibernate, and Liquibase options. See the jdbc.prod.properties file for what gets set. All these options can be overridden in your /etc/irida/irida.conf file.

The spring.profiles.active=prod option will enable all the production features of IRIDA (web server, project synchronization, email announcements, NCBI uploads, analysis engine).

For high usage or high load installations of IRIDA, you may consider deploying these features to multiple servers. For more on this feature, see the Multi Web Server Configuration section.

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
assembly.file.base.directory=/opt/irida/data/assembly
pipeline.plugin.path=/etc/irida/plugins

##### 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
file.processing.process=true

##### OAuth2 JWT security settings.
# Default keystore for holding public/private keys required for OAuth2 JWK Access Token encryption/decryption
oauth2.jwk.key-store=/etc/irida/jwk-key-store.jks
oauth2.jwk.key-store-password=SECRET

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

## MySQL (or MariaDB)
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver
spring.jpa.database-plaform.dialect=org.hibernate.dialect.MySQL55Dialect
# Deprecated as of 22.01
#jdbc.driver=com.mysql.jdbc.driver
#hibernate.dialect=org.hibernate.dialect.MySQL55Dialect

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

## Connection settings:
spring.datasource.username=test
spring.datasource.password=test
# Deprecated as of 22.01
#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).
spring.jpa.hibernate.ddl-auto=
spring.jpa.properties.hibernate.hbm2ddl.import_files=
# Deprecated as of 22.01
#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.
spring.jpa.show-sql=false
# Deprecated as of 22.01
#hibernate.show_sql=false

## Connection Pool settings:
spring.datasource.dbcp2.intial-size=10
spring.datasource.dbcp2.max-active=20
spring.datasource.dbcp2.test-on-borrow=true
spring.datasource.dbcp2.test-on-return=true
spring.datasource.dbcp2.test-while-idle=true
# Deprecated as of 22.01
#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.
spring.datasource.dbcp2.validation-query=select 1
# Deprecated as of 22.01
#jdbc.pool.validationQuery=select 1

spring.datasource.dbcp2.max-wait=10000
spring.datasource.dbcp2.remove-abandoned=true
spring.datasource.dbcp2.log-abandoned=true
spring.datasource.dbcp2.remove-abandoned-timeout=60
spring.datasource.dbcp2.max-idle=10
# Deprecated as of 22.01
#jdbc.pool.maxWait=10000
#jdbc.pool.removeAbandoned=true
#jdbc.pool.logAbandoned=true
#jdbc.pool.removeAbandonedTimeout=60
#jdbc.pool.maxIdle=10

## Configure the password expiry time in days.  A value of -1 will set no expiry.
security.password.expiry=-1

###############################################################################
# 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

# The number of threads used to handle analysis tasks (e.g., submitting files to Galaxy and downloading results).
# If the maximum number of workflow threads is large, it may improve performance to increase this value as well.
#irida.scheduled.analysis.threads=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
# Adjusts Control Keep Alive Timeout value, which can assist in keeping an FTP connection alive for long file transfers.
# See <https://commons.apache.org/proper/commons-net/apidocs/org/apache/commons/net/ftp/FTPClient.html>.
#ncbi.upload.controlKeepAliveTimeoutSeconds=300
#ncbi.upload.controlKeepAliveReplyTimeoutMilliseconds=2000
# Adjusts whether or not to use active vs passive mode for the FTP connection.
# Passive mode is recommended if you are behind a firewall/NAT.
#ncbi.upload.ftp.passive=true

# A list of workflow types to disable from display in the web interface
# For example `irida.workflow.types.disabled=ASSEMBLY_ANNOTATION,ASSEMBLY_ANNOTATION_COLLECTION,BIO_HANSEL,MLST_MENTALIST,REFSEQ_MASHER,SISTR_TYPING,PHYLOGENOMICS`
# If you wish to re-enable any default disabled pipelines, you can set this to an empty value (i.e., irida.workflow.types.disabled=)
# If you wish to keep the default disabled pipelines but include additional pipelines, you can set to (irida.workflow.types.disabled=SISTR_TYPING,MLST_MENTALIST) and include your own after this list.
#irida.workflow.types.disabled=

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.
    • assembly.file.base.directory=/opt/irida/data/assembly - Assemblies uploaded into IRIDA.
    • pipeline.plugin.path=/etc/irida/plugins - Directory to search for pipeline plugins.
  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.
    • file.processing.process=true - Whether to run the file processors on the current machine. This can be set to false if you’re running multiple IRIDA servers and want to improve UI performance on a machine.
  3. Database connection information:
    • spring.datasource.url=jdbc:mysql://localhost:3306/irida_test
    • spring.datasource.username=test
    • spring.datasource.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.
    • irida.workflow.analysis.threads - The number of threads to use for handling analysis/workflow tasks. For larger installations this number can be increased. Increasing beyond irida.workflow.max-running is unlikely to give any additional performance boost.
  5. NCBI SRA export configuration - An SRA bulk upload user account must be created with NCBI to allow automated SRA uploads. Contact NCBI’s SRA staff at sra@ncbi.nlm.nih.gov and ask for information about setting up a “Center account for simplified format using FTP” for more information.
    • 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.
  6. Security configuration
    • security.password.expiry - The number of days a password is valid for in IRIDA. After a password expires the user will be required to create a new one. Passwords cannot be reused.
  7. OAuth2 JWK security configuration - IRIDA uses JWT (Json Web Tokens) for OAuth2 and as such requires a Java Key Store with an entry stored in PKCS12 format. The key pair entry can be in either RSA or EC (curves allowed are P-256, P-384, and P-121) format. The password for the keystore must be the same as the password for the key entry (This is default for PKCS12 format). (Note: these keys have nothing to do with SSL).
    • oauth2.jwk.key-store=/etc/irida/jwk-key-store.jks - The location of the Java Key Store
    • oauth2.jwk.key-store-password=SECRET - The Java Key Store password

OAuth2 JWK Java Key Store generation

The Java Key Store required to encrypt and decrypt the JWT’s can be generated with the following commands:

keytool -genkeypair -alias JWK -keyalg RSA -noprompt -dname "CN=irida.bioinformatics.corefacility.ca, OU=ID, O=IRIDA, L=IRIDA, S=IRIDA, C=CA" -keystore /etc/irida/jwk-key-store.jks -validity 3650 -storepass SECRET -keypass SECRET -storetype PKCS12

This will generate a Java Key Store with an entry aliased JWK with an expiry of 10 years and a password of SECRET.

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
mail.server.password=
mail.server.port=25

# 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

# This value may be un-commented and edited to display a dismissable warning
# above all analysis results and metadata pages.
# irida.analysis.warning=Note: These results may be preliminiary

# Comma separated locales enabled for IRIDA.  Currently only the English 'en'
# locale is fully internationalized, and it is enabled by default.
# locales.enabled=en

# Default locale to display before a user is logged in.  Currently only the English 'en'
# locale is fully internationalized, and it is enabled by default.
# locales.default=en

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

To add new internationalization to your IRIDA server, see the internationalization guide.

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://github.com/phac-nml/irida/releases

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.

Multi Web Server Configuration

When IRIDA is deployed in a higher load environment, it may be preferable to deploy multiple IRIDA web application servers to handle all web requests, processing, and scheduled tasks. IRIDA has the ability to run in a multi-server mode which will distribute these tasks among multiple servers. This is achieved through the use of Spring profiles. Deploying IRIDA in this fashion allows IRIDA administrators to maintain good performance for users of the IRIDA web application, while offloading some of the more resource-hungry processing tasks to additional servers. Multiple profiles may be applied to individual servers to group some of the tasks onto one machine.

Note: The prod, dev profiles and multi server configuration profiles below cannot be used at the same time. Doing so may result in corrupt analysis data sets.

The different application profiles and their functions are the following:

To launch an IRIDA application server with one (or more) of these profiles, you must enable the profile with the spring.profiles.active variable in your Tomcat configuration. For example to run an IRIDA server with the web and analysis profiles active, you would set the following configuration:

spring.profiles.active=web,analysis

See the Servlet Container Configuration section for more on setting the spring.profiles.active and irida.db.profile variables for Tomcat.

Example moderate load deployment:

A deployment of this style provides an additional server for file processing, while maintaining high performance for users of the web server.

Example high load deployment:

A deployment of this style provides multiple servers for file processing, while maintaining high performance for users of the web server. It also offloads any networking lag introduced by synchronization jobs, uploading to NCBI, or analysis jobs.

Deployment Tips

Since IRIDA often deals with large sequence files, you can occasionally run into issues with file upload sizes being too large for the server IRIDA is running on. There are 2 directories where Tomcat stores temporary files as they’re being uploaded which can be configured to run on some larger shared storage.

First is Tomcat’s “temp” directory. You can configure Tomcat to use another directory by setting the CATALINA_TMPDIR variable in tomcat.conf (on Centos this can be found in /etc/tomcat):

CATALINA_TMPDIR=/Some/Larger/Shared/Storage/temp

The second is Tomcat’s “work” directory. This can be configured in server.xml (on Centos this can be found in /etc/tomcat). You can set the workDir variable in the <Host> section. Be careful not to modify any other variables:

<Host ... workDir="/Some/Larger/Shared/Storage/work">
...
</Host>