iGene can be installed an any modern Linux or BSD installation as a standard service running under Java 1.8 and Tomcat 7+. At present, only MySQL server is supported (Version 5.6 or higher)
These instructions are for Ubuntu 17.04. The instructions should work on most other distributions with minor changes (e.g. Service and package management)
1) Install MySQL Server. This step should only be performed if you do not already have a database server setup
$ sudo apt-get update
$ sudo apt-get install mysql-server
$ sudo service mysql start
2) Create a database using your connection details. The storage engine should be InnoDB and formatting should be in UTF8
Only perform this step if you do not already have a database to connect to
$ mysql -u -p
mysql> SET storage_engine=InnoDB;
mysql> create database igene CHARACTER SET utf8 COLLATE utf8_bin;
mysql> exit;
3) Install the Java runtime environment. IGene requires a Java 8 runtime.
$ sudo apt-get install default-jdk
4) Installing and configuring Tomcat
These instructions will not use the package manager and instead will install the Tomcat distribution directly from Apache.
Firstly, setup a user account to run Tomcat. The Tomcat service should not run under root for security purposes. These instructions will install Tomcat to /opt/tomcat. This directory should be big enough to contain the iGene install files, temporary files and the logs.
$ sudo groupadd tomcat
$ sudo useradd -s /bin/false -g tomcat -d /opt/tomcat tomcat
Go to http://tomcat.apache.org/download-80.cgi and grab the latest version of Tomcat 8. Once downloaded extract and move to /opt/tomcat
$ wget -O apache-tomcat-8.5.16.tar.gz http://ftp.ps.pl/pub/apache/tomcat/tomcat-8/v8.5.16/bin/apache-tomcat-8.5.16.tar.gz?lfkfkfkfkfcbiecb
(Optional) Validate the downloaded file matches the MD5.
Run the following two commands and check the MD5 sums match
$ curl https://www.apache.org/dist/tomcat/tomcat-8/v8.5.16/bin/apache-tomcat-8.5.16.tar.gz.md5 | awk '{print $1}'
$ md5 apache-tomcat-8.5.16.tar.gz
Extract and copy to install location
$ sudo tar -xzvf apache-tomcat-8.5.16.tar.gz
$ sudo mv apache-tomcat-8.5.16 /opt/tomcat
Next, create the iGene home folder and give permission to Tomcat to read and write. This folder will contain the iGene filesystem (e.g. PDFs, Reports, etc).
$ sudo mkdir /home/igene
$ sudo chmod -R 755 /home/igene
Ensure Tomcat has access to its own work area.
$ sudo chgrp -R tomcat /opt/tomcat
$ sudo chown -R tomcat /opt/tomcat
$ sudo chmod -R 755 /opt/tomcat
Tomcat can normally be started directly from the bin/startup.sh command, however it is better to create a startup service. For other distributions and OSes, please consult the documentation on how to do this
Create a new file:
$ sudo nano /etc/systemd/system/tomcat.service
Paste in the following and save the file:
[Unit]
Description=Apache Tomcat Web Server
After=network.target
[Service]
Type=forking
Environment=JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64/jre
Environment=CATALINA_PID=/opt/tomcat/temp/tomcat.pid
Environment=CATALINA_HOME=/opt/tomcat
Environment=CATALINA_BASE=/opt/tomcat
Environment='CATALINA_OPTS=-Xms512M -Xmx1024M -server -XX:+UseParallelGC'
Environment='JAVA_OPTS=-Djava.awt.headless=true -Djava.security.egd=file:/dev/./urandom'
ExecStart=/opt/tomcat/bin/startup.sh
ExecStop=/opt/tomcat/bin/shutdown.sh
User=tomcat
Group=tomcat
UMask=0007
RestartSec=15
Restart=always
[Install]
WantedBy=multi-user.target
Now Tomcat is ready to be started. Start the service and check the status using the following commands:
Reload the daemon engine to pick up the startup script:
$ sudo systemctl daemon-reload
Start Tomcat:
$ sudo systemctl start tomcat
Verify Tomcat has worked:
$ sudo systemctl status tomcat
Once verified, shut down Tomcat to install iGene. This will prevent the application trying to run before the database connection has been setup
$ sudo systemctl stop tomcat
(Optional) To configure Tomcat to startup automatically upon system boot, run the following:
$ sudo systemctl enable tomcat
By default, Tomcat only allocates a small amount of RAM for running processes. iGene requires at least 2GB of RAM to run smoothly. To configure Java/Tomcat to allocate more RAM, create a new file called /opt/tomcat/bin/setenv.sh and add some environment variables to CATALINA_OPTS
sudo nano /opt/tomcat/bin/setenv.sh
Add the following to the file and save: (This will allow any process on Tomcat to use 2GB of RAM. This can be increased if required)
export CATALINA_OPTS="$CATALINA_OPTS -Xms512m"
export CATALINA_OPTS="$CATALINA_OPTS -Xmx2048m"
export CATALINA_OPTS="$CATALINA_OPTS -XX:MaxMetaspaceSize=256m"
The final step is to configure the iGene home directory in Tomcat. This is a startup variable that will be passed to iGene.
Locate the file /opt/tomcat/conf/server.xml, and modify the area shown in the clip below to include the igene_home variable
$ nano /opt/tomcat/conf/server.xml
<Host name="localhost" base="webapps"
unpackWARs="true" autoDeploy="true"
xmlValidation="false" xmlNamespaceAware="false">
<Context docBase="ROOT.war" path="">
<Parameter name="igene_home" value="/home/igene" override="false" />
</Context>
5) Configuring the database connection
For Linux/BSD based installations, iGene presently only supports MySQL Server 5.6+. The connection is configured via a config file which is provided along with the application by Genial Genetics. This file is called config and is placed directly into the igene home folder, i.e. /home/igene/config
$ nano /home/igene/config
Find the connection details in the file as shown below and modify the address, database, username and password as required.
hibernate.connection.username={username}
hibernate.connection.password={password}
hibernate.connection.url=jdbc\:mysql\://{address}/{database}
If this is the first time iGene has been ran on this machine and the database is blank, iGene will setup the schema automatically
6) Installing iGene into Tomcat
Genial Genetics provide iGene packaged as a .WAR file. A WAR file is a web archive used by Tomcat and other Java web containers. The following steps can be used to also upgrade the installation of iGene.
Stop the Tomcat Service. This is advised to prevent a premature startup of the application
$ sudo systemctl stop tomcat
Move/Copy the ROOT.war file provided by Genial Genetics into the /opt/tomcat/webapps folder, e.g:
$ sudo mv /home/tony/ROOT.war /opt/tomcat/webapps/
7) Starting iGene and monitoring the logs
Once all the above steps have been completed, start up Tomcat:
$ sudo systemctl start tomcat
Tomcat will extract the ROOT.war file out into a folder called ROOT in the webapps folder. This folder contains all the files required to run the application. Once extracted, the application will be started up.
Tomcat logs messages inside /opt/tomcat/logs/catalina.out. During startup, monitor this file for any issues. iGene will report any problems such as the inability to connect to the database or other issues. When reporting bugs, please provide the relevant part of the log file to Genial Genetics