This document describes how to install the IRIDA web interface. We assume that you have completed installing and configuring Galaxy.
- Deploying IRIDA
The IRIDA platform currently consists of three, separate components:
- The web interfaces: User interface and API,
- Galaxy, and
- 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.
The following prerequisites are required for running the IRIDA web interfaces:
- Java 11 or higher.
- A working servlet container supporting Servlet 3.1 (Tomcat, version 8 or higher, for example)
- A working database server (the application is tested on MySQL or MariaDB).
- A working install of Galaxy (we recommend that you run Galaxy and the IRIDA web interface on separate machines). The install guide assumes that you are using Bash
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.
- Windows: Since the IRIDA Platform web interfaces are written in Java, they can, in theory, be deployed on a Windows host. We do not officially support or test deployment on Windows servers, so no instructions are provided.
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:
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:
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
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.
All IRIDA configuration files are stored in
/etc/irida/. The main IRIDA configuration file should be written to
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:
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:
- 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.
- 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.
- Database connection information:
- Galaxy connection information for executing pipelines:
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-runningis unlikely to give any additional performance boost.
- 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 firstname.lastname@example.org 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.
- 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.
- 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
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:
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.
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.
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.
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:
- Automatically prepare the database on your system (using Liquibase) using the database connection details you specified in Core Configuration.
- Install any internally configured workflows.
- 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
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:
The default administrator username and password are:
- Username: admin
- Password: password1
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.
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:
web- The IRIDA user interface and REST API web application servers. This is the portal for user interactions. If using more than 1
webserver, users & REST API clients must somehow be routed to the other servers. Minimum number of servers: 1, Recommended: 1, max: unlimited.
analysis- Run the IRIDA analysis engine. This profile launches and monitors progress of all analysis pipelines in IRIDA. Required to be active on exactly 1 server.
processing- File processing pipeline for uploaded sequencing data. This is the highest load profile as it performs all file management for uploaded sequencing data. Adding additional servers for this profile will speed up file processing for higher load installations. Minimum number of servers: 1, recommended: 2, max: unlimited but diminishing returns with higher numbers of servers.
sync- Synchronizing remote projects. This profile performs the remote api project synchronization task to pull remote sequencing data and metadata to a local installation. Required to be active on exactly 1 server.
ncbi- Uploading data to NCBI. This profile runs the NCBI SRA uploader task to send project and sample data to NCBI’s SRA. Required to be active on exactly 1 server.
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
analysis profiles active, you would set the following configuration:
See the Servlet Container Configuration section for more on setting the
irida.db.profile variables for Tomcat.
Example moderate load deployment:
- Server 1 -
- Server 2 -
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:
- Server 1 -
- Server 2 -
- Server 3 -
- Server 4 -
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.
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
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>