====== Installing Molgenis on Ubuntu ======

Note that the below procedure would not have been possible without the help of [[https://nl.linkedin.com/in/djvanenckevort|David van Enckevort]]. The document highlights the installation of the Molgenis web application.  If you would like to develop or contribute (code) to the project, you are better off forking the [[https://github.com/molgenis/molgenis|github version]].

===== Requirements =====

Install Java 8 (my favorite is the Oracle JDK).  There are many [[http://www.webupd8.org/2012/09/install-oracle-java-8-in-ubuntu-via-ppa.html|websites]] explaining how to do this, but the TL;DR version is:

<code bash>
sudo apt-get install software-properties-common
sudo add-apt-repository ppa:webupd8team/java
sudo apt-get update
sudo apt-get install oracle-java8-installer # some annoying licence acceptance terms will pop up
sudo apt-get install oracle-java8-set-default
</code>

When you are done  ''java -version'' and ''javac -version'' should yield the Java 8 version and build number.  **Note that version 8 is a requirement for the molgenis platform.**

You will also need to install Tomcat 7.  This is straightforward with 

<code bash>
sudo apt-get install tomcat7
</code>

Molgenis uses MySQL for its backend - so this needs to be installed using the following:

<code bash>
sudo apt-get install mysql-server libmysql-java
</code>

During this installation of MySQL you will be prompted for the root password, make sure to use something memorable.

Note that ''libmysql-java'' installs the JDBC connection driver to MySQL.  This JDBC Driver is a java class which needs to be made available to tomcat.  Two ways of doing this are either including ''/usr/share/java/mysql.jar'' in the tomcat7 user's CLASSPATH env variable or copying this file to the Tomcat ''lib'' directory as follows:

<code bash>
sudo cp -v /usr/share/java/mysql.jar /usr/share/tomcat7/lib 
</code>

Note that Tomcat should be restarted after this file is copied over (for the class to be loaded).  This can be done with:

<code bash>
sudo service tomcat7 restart
</code>

===== Installation Procedure =====



  - Tomcat will require some further configuration for Molgenis to run
    - First edit the tomcat defaults (these are found in ''/etc/default/tomcat7'').  This special location is used to store admin settings which are likely to change and you want to keep across updates. ''sudo vim /etc/default/tomcat7''
    - Add the following line ''JAVA_HOME=/usr/lib/jvm/java-8-oracle'' to the file to make sure the JVM is the oracle one we installed above
    - In the ''JAVA_OPTS'' line (this is used to set the JVM parameters):
      - **Change** ''-Xmx'' parameter to whatever its value to ''-Xmx1g''
      - **Add** The following two properties ''-Dmolgenis.home=/var/lib/molgenis -Dlog4j.configuration=log4j-molgenis.properties''
      - The resulting line should look something like:<code bash>
JAVA_OPTS="-Djava.awt.headless=true -Xmx1g -XX:+UseConcMarkSweepGC -Dmolgenis.home=/var/lib/molgenis -Dlog4j.configuration=log4j-molgenis.properties"
</code>
    - After these changes to Tomcat you will need to restart the application server with:<code bash>
sudo service tomcat7 restart
</code>
  - MySQL will also require some additional setup (basically creating a database, a username and a password).<code bash>
mysql -u root -p -e "create database molgenis; grant all on molgenis.* to 'molgenis'@'localhost' identified by 'YOUR_PASSWORD_HERE'; flush privileges;"
</code>
  - Create a molgenis directory which is writable by the ''tomcat7'' user (this is used for state information).<code bash>sudo mkdir /var/lib/molgenis
</code>
    - Set the correct permissions with '' sudo chown tomcat7:tomcat7 /var/lib/molgenis''
  - We need to create a properties file called ''molgenis-server.properties'' in the molgenis home directory (i.e. ''/var/lib/molgenis'') specified above.<code bash>
sudo vim /var/lib/molgenis/molgenis-server.properties
</code>
    - This properties file should contain the following (please make sure to substitute the MySQL molgenis user password with the correct one):<code properties>
#Molgenis server properties

molgenis.version=13
admin.password=MOLGENIS_ADMIN_PASSWORD_HERE_CHANGE!!!
db_uri=jdbc\:mysql\://localhost/molgenis
db_driver=com.mysql.jdbc.Driver
db_user=molgenis
db_password=MYSQL_MOLGENIS_PASSWORD_HERE_CHANGE!!!
mail.host=localhost
mail.port=25
</code>
    - Note: The ''admin.password'' property is the one which the user ''admin'' uses to log in the molgenis system (from the frontend).
    - The file is sensitive as it contains passwords, and should therefore be secured using the following:<code bash>
sudo chown tomcat7:tomcat7 /var/lib/molgenis/molgenis-server.properties
sudo chmod 600 /var/lib/molgenis/molgenis-server.properties
</code>
  - Download the latest version of molgenis web application file (this is in the form of a Java war).
    - Do this by searching for //molgenis-app// in the [[http://search.maven.org/|maven repository]]
    - Download the war file by using wget. e.g.<code bash>
wget http://search.maven.org/remotecontent?filepath=org/molgenis/molgenis-app/1.19.0/molgenis-app-1.19.0.war -O molgenis-app-1.19.0.war</code>
  - Rename the downloaded war file to ''ROOT.war'' (case important).  This is an annoying and necessary limitation
  - Make sure owner tomcat7 owns the file, ''sudo chown tomcat7:tomcat7 ROOT.war''
  - Copy the newly renamed ''ROOT.war'' to the Tomcat webs directory (by default this is in ''/var/lib/tomcat7/webapps'')<code bash>
sudo cp -vp ROOT.war /var/lib/tomcat7/webapps
</code>
  - The above will automatically start deploying the molgenis app on Tomcat.  If you want to follow what is going on, **before** copying set a ''sudo tail -f /var/log/tomcat7/catalina.out''
  - When the molgenis web application deploys you should see something like:
<konsole>
<nowiki>
Aug 21, 2015 2:32:41 PM org.apache.catalina.startup.HostConfig deployWAR
INFO: Deploying web application archive /var/lib/tomcat7/webapps/ROOT.war
14:33:04.641 [localhost-startStop-1] INFO  o.m.d.e.f.EmbeddedElasticSearchServiceFactory - Embedded elasticsearch server started, data path=[/var/lib/molgenis/data]
14:33:07.379 [localhost-startStop-1] INFO  o.m.d.version.MolgenisUpgradeService - MetaData version:13, current version:13 upgrade not needed
14:33:07.395 [localhost-startStop-1] INFO  o.m.a.WebAppConfig$$EnhancerBySpringCGLIB$$183b5b00 - Reindexing repositories....
14:33:09.499 [localhost-startStop-1] INFO  o.m.a.WebAppConfig$$EnhancerBySpringCGLIB$$183b5b00 - Reindexing done.
14:33:09.551 [localhost-startStop-1] WARN  o.m.data.mysql.MysqlRepository - Table for entity tags already exists. Skipping creation
14:33:09.576 [localhost-startStop-1] WARN  o.m.data.mysql.MysqlRepository - Table for entity packages already exists. Skipping creation
14:33:09.678 [localhost-startStop-1] WARN  o.m.data.mysql.MysqlRepository - Table for entity attributes already exists. Skipping creation
14:33:09.707 [localhost-startStop-1] WARN  o.m.data.mysql.MysqlRepository - Table for entity entities already exists. Skipping creation
14:33:34.421 [localhost-startStop-1] ERROR o.m.d.support.AbstractEntityMetaData - No idAttribute specified for entityFileMeta, this attribute is required
14:33:34.427 [localhost-startStop-1] ERROR o.m.d.support.AbstractEntityMetaData - No idAttribute specified for entityFileMeta, this attribute is required
14:33:52.166 [localhost-startStop-1] INFO  o.m.d.jpa.JpaRepositoryRegistrator - Registered JPA importer
14:33:52.167 [localhost-startStop-1] INFO  o.m.d.m.EmxImportServiceRegistrator - Registered EMX import service
14:33:52.940 [localhost-startStop-1] INFO  o.m.f.db.WebAppDatabasePopulator - initializing application database
14:34:40.345 [localhost-startStop-1] INFO  o.m.f.db.WebAppDatabasePopulator - initialized application database
14:34:40.920 [localhost-startStop-1] INFO  o.m.u.m.MenuManagerServiceImpl - Creating default menu from XML
14:34:43.557 [localhost-startStop-1] INFO  o.m.script.ScriptRunnerFactory - Registering Script type R.
14:34:45.561 [localhost-startStop-1] INFO  o.m.o.i.OntologyImporterServiceRegistrator - Registered ontology import service
14:34:51.415 [localhost-startStop-1] INFO  o.m.o.i.OntologyScriptInitializerImpl - Script entity "roc" has been added to the database!
14:34:51.417 [localhost-startStop-1] INFO  o.m.script.ScriptRunnerFactory - Registering Script type python.
Aug 21, 2015 2:34:54 PM org.apache.coyote.AbstractProtocol start
INFO: Starting ProtocolHandler ["http-bio-8080"]
Aug 21, 2015 2:34:54 PM org.apache.catalina.startup.Catalina start
INFO: Server startup in 133414 ms</nowiki>
</konsole>

You can access the molgenis web app by pointing your web browser to [[http://127.0.0.1:8080|http://127.0.0.1:8080]]