This guide describes how to set up a workstation for hacking on IRIDA.
- General Requirements
- Install instructions
- Install instructions for Ubuntu
- Install instructions for CentOS
- Post-software install setup (Ubuntu and CentOS)
- Setting up Galaxy
- Front End Development Setup
You’re required to install a few different pieces of software on your machine before you can get started on hacking IRIDA:
- DB: A MySQL or MariaDB server,
- Languages: Java 8 (we have a hard requirement on Java 8), Python, Node
- Build: Apache Maven, Bower
- SCM: Git
- IDE: Eclipse, Netbeans, IntelliJ, vim… (whatever you want, really).
Install instructions for Ubuntu
These instructions work for a fresh, up-to-date install of Ubuntu 14.04 LTS. No guarantees if you’re using some other version of Ubuntu or some derivative of Ubuntu.
# required for using the `apt-add-repository` command sudo apt-get install --yes --no-install-recommends python-software-properties # add the ppa for downloading the oracle java installer sudo apt-add-repository --yes ppa:webupd8team/java # update sources sudo apt-get update # You will be prompted to set a root password for mysql and to accept the license for the Java installer. sudo apt-get install --yes --no-install-recommends mysql-server maven git oracle-java8-installer
Install instructions for CentOS
These instructions work for a fresh, up-to-date install of CentOS 7. No guarantees if you’re using some other version of CentOS or some other RedHat-like distro.
CentOS (unfortunately) isn’t as easy to set up as Ubuntu, you will have to manually install several bits of software.
Post-software install setup (Ubuntu and CentOS)
Once you’ve installed all of the prerequisites with your package manager (or manually), you can proceed with configuring MySQL (creating a user account and setting permissions), checking out IRIDA from our git repository, and running IRIDA on the command-line. You’re on your own for IDE configuration.
You’ve probably already figured out how to clone IRIDA if you’re reading this documentation. Nevertheless, for completeness sake, you can clone IRIDA on the command-line like so:
git clone http://irida.corefacility.ca/gitlab/irida/irida.git # Or, alternatively, git clone https://github.com/phac-nml/irida.git
Importing IRIDA into an IDE is left to the developer.
IRIDA uses some custom libraries that are either a) not currently available in a Maven repository, or b) a custom version of the software available in Maven central. We provide a convenient
bash script for installing our additional Java dependencies in the
cd irida/lib/ bash install-libs.sh
Many of IRIDA’s properties can be configured by creating a file
/etc/irida/irida.conf. The file is a basic key/value file (keys and values are separated by an
= sign). A short example:
# configure liquibase to manage the database schema liquibase.update.database.schema=false # disable hibernate's automatic schema creation hibernate.hbm2ddl.auto= # disallow hibernate from importing any data hibernate.hbm2ddl.import_files=
The sections below will include the keys that you can use to override the default behaviour.
IRIDA is configured to use the following credentials by default:
- Username (
- Password (
- Database (
You’ll need to permit those user credentials to create the tables in the database. A quick one-liner for that is:
echo "grant all privileges on irida_test.* to 'test'@'localhost' identified by 'test';" | mysql -u root -p
Also create the database if it doesn’t exist:
echo "create database irida_test;" | mysql -u root -p
In order to run local integration tests, the database
irida_integration_test is used instead. This database requires permissions from user
'test'@'localhost'. To grant such permissions a quick one-liner is:
echo "grant all privileges on irida_integration_test.* to 'test'@'localhost';" | mysql -u root -p
Configure Filesystem Locations
IRIDA stores much of its metadata in the relational database, but all sequencing and analysis files are stored on the filesystem. Directory configuration is:
- Sequencing Data:
- Reference Files:
- Analysis Output:
If the directories that are configured do not exist (they don’t likely exist if you don’t configure them), IRIDA will default to automatically creating a temporary directory using Java’s
You can verify that you’ve installed everything correctly in one of two ways:
- Minimal verification: Check to see that Jetty starts, or
- Maximal verification: Run the complete test suite.
Checking to see that Jetty starts will ensure that you’re able to start hacking on the UI or the REST API. If you’re going to be working on Galaxy-related features, you should probably run the complete test suite as it runs a Docker version of Galaxy and verifies that communication between IRIDA and Galaxy will work properly. Keep in mind that the complete test suite execution currently takes approximately 1 hour to complete.
Checking to see that Jetty starts
IRIDA uses Maven for build and dependency management. You can check to see that Jetty starts like so:
mvn clean jetty:run
Database first-time setup
When first starting up Jetty, you’ll need to have the database created and populated, which can be done by running the following script:
This will create the database schema and import some testing data. This can also be used to drop then recreate the database and reimport the starting dataset when a clean database is needed.
For all subsequent runs, simply run the script with no options:
This will update the database if the schema has been changed, but without dropping all of the tables beforehand, which will cause Jetty to start up much faster.
To run the full integration test suite for IRIDA please run the following:
This will run all the integration test profiles using Maven, and print out reports for each profile.
Setting up Galaxy
Please refer to the Galaxy Install Guide for information on setting up Galaxy to use with IRIDA. The simplest method is to use Docker, but if new tools are being developed for Galaxy and integrated into IRIDA it is recommended to install a non-Docker version of Galaxy.
Front End Development Setup
You will need to run
yarn install to install all dependencies required to run the following from the command line.
yarn sass- compile all
.cssfiles, with sourcemaps.
yarn build- compile all es6 files to es2015.
yarn start- use when developing front end code. Webpack will monitor for changes to the entry files, compile them, and then updates the browser with the changes.
eslint-plugin-prettier (see below for enabling eslint in IntelliJ and VS Code).
There is good editor integration for Prettier formatting
IntelliJ IDEA Setup
- Check the “Enable” checkbox.
- Node interpreter should be you system node by default.
- ESLint package is the
eslintwithin the projects
- Configuration file is the
Visual Studio Code Setup
- Open the quick open panel
- Copy and paste:
ext install vscode-eslintand press enter.
ESLintand click “Install”.
- Click “Enable” and allow VS Code to restart.