PhenoTips » Administration Guide » PhenoTips Installation Instructions » PhenoTips Installation Instructions on Linux/Tomcat/MySQL

PhenoTips Installation Instructions on Linux/Tomcat/MySQL

PhenoTips Installation Instructions on Linux/Tomcat/MySQL

The standalone package is a convenient way to try out PhenoTips without a dedicated server, but it is not optimized for production use. The war package, on the other hand, gives complete freedom over the choice of servlet container, database system, performance optimizations, allocated memory, etc. But due to this freedom, the installation process is also harder.

These instructions are specific to a Linux/Tomcat/MySQL deployment. For other environments see the generic WAR installation instructions.

Requirements

Java 1.7+, a servlet container supporting the Servlet 3.0 specification, and a relational database. Although it is not mandatory to have external access to the internet, it is recommended that at least during the initial installation and further upgrades to allow access to nexus.phenotips.org for PhenoTips to be able to download some of its required files. A SMTP server is also required for sending password reset emails, but otherwise it is not needed, and it can be on a different server if there's already a global mailsending server used in the institution.

The recommended set up consists of:

  • GNU/Linux as the operating system
  • JDK 1.7+, either Open JDK or Oracle JDK
  • Apache Tomcat 7+ as the servlet container
  • MySQL with InnoDB as the database
  • Apache HTTPD with mod_proxy_ajp as a reverse proxy
  • Postfix for sending emails

Everything should be configured with the UTF-8 encoding, especially MySQL and Tomcat which have different default encodings.

Server configuration

Follow the operating system specific instructions for installing the Java runtime, Tomcat, MySQL, and the (optional) Apache HTTPD server and mail server.

Configuring Tomcat

For good performance, PhenoTips requires more memory than Tomcat allocates by default, so the startup configuration must be updated with custom -Xmx and -XX:MaxPermSize parameters. On GNU/Linux, this is usually done in /etc/tomcat/tomcat.conf, /etc/default/tomcat7 or /etc/conf.d/tomcat-7. Find the right file, then add the following line in it:

JAVA_OPTS="${JAVA_OPTS} -Xmx12048m -XX:MaxPermSize=256m"

If you have a more powerful server, feel free to increase the -Xmx parameter even further.

Contrary to modern web standards, Tomcat still uses the older ISO-8859-1 encoding by default, and this prevents non-ASCII characters from working. To fix this, the server.xml configuration file must be edited. This can be usually found in /etc/tomcat/server.xml or /etc/tomcat-7/server.xml. Inside this file, search for the two <Connector elements, one for the 8080 port and one for the 8009 port, and add the following attribute: URIEncoding="UTF-8":


   <Connector port="8080" protocol="HTTP/1.1"
              connectionTimeout="20000"
              redirectPort="8443" URIEncoding="UTF-8" />

...

   <Connector port="8009" protocol="AJP/1.3" redirectPort="8443" URIEncoding="UTF-8" />

If the 8009 AJP connector isn't enabled, enable it by removing the XML comment markup around it.

Download the latest PhenoTips WAR distribution, unzip it in a directory named phenotips (or another name of your choice), and move it to the Tomcat webapps directory, usually /var/lib/tomcat/webapps, /var/lib/tomcat-7/webapps/ or /usr/local/tomcat/webapps/. If you don't use Tomcat for other applications, you can remove the existing ROOT webapp and use ROOT as the name of the application directory, which would shorten the final URLs where PhenoTips is accessed.

Make sure the user running Tomcat (tomcat or tomcat7) has read access on all the application files. You should chown -R the application directory to that user.

Setting up the MySQL database

You will have to create the MySQL database and grant access to a user:

create database phenotips default character set utf8 default collate utf8_bin;
grant all privileges on phenotips.* to phenotips@localhost identified by "choose a password";

Feel free to use another database name and user name. The PhenoTips application will take care of the table creation itself.

You will have to edit webapps/phenotips/WEB-INF/hibernate.cfg.xml, comment out the default HSQLDB configuration, uncomment the MySQL configuration, and set the proper database name, username and password:

   <!-- MySQL configuration.
         Uncomment if you want to use MySQL and comment out other database configurations.
         Notes:
           - if you want the main wiki database to be different than "xwiki"
             you will also have to set the property xwiki.db in xwiki.cfg file
    -->

   <property name="connection.url">jdbc:mysql://localhost/phenotips</property> <!-- Replace phenotips with the chosen database name -->
   <property name="connection.username">phenotips_user</property> <!-- Replace phenotips_user with the chosen username -->
   <property name="connection.password">phenotips_password</property> <!-- Replace phenotips_password with the chosen password -->
   <property name="connection.driver_class">com.mysql.jdbc.Driver</property>
   <property name="dialect">org.hibernate.dialect.MySQL5InnoDBDialect</property>
   <property name="dbcp.poolPreparedStatements">true</property>
   <property name="dbcp.maxOpenPreparedStatements">20</property>
   <mapping resource="xwiki.hbm.xml"/>
   <mapping resource="feeds.hbm.xml"/>
   <mapping resource="mailsender.hbm.xml"/>

You must also edit webapps/phenotips/WEB-INF/xwiki.cfg and add the following line (replace with the right database name):

xwiki.db=phenotips

Make sure the database name created when setting up MySQL database matches the names set in webapps/phenotips/WEB-INF/xwiki.cfg and webapps/phenotips/WEB-INF/hibernate.cfg.xml.

By default MySQL only accepts packets that are smaller than 1MB. You might you get an error with the following message when saving complex patient records, or when deleting patient records with attached files:

 com.mysql.jdbc.PacketTooBigException: Packet for query is too large (MMM > NNN). You can change this value on the server by setting the max_allowed_packet variable.

You should increase the packet size to 64M or more by editing /etc/my.cnf or /etc/my.cnf.d/server.cnf, in the [mysqld] or [server] section, and adding the following line:

 max_allowed_packet = 64M

Configuring PhenoTips

PhenoTips needs to have write access to a directory where it can write all its work data and temporary files. /var/lib/phenotips/ is a good default choice, but feel free to choose another path. Edit webapps/phenotips/WEB-INF/xwiki.properties and edit the following line:

environment.permanentDirectory=/var/lib/phenotips/

Make sure this directory has read-write access for the user running Tomcat, usually tomcat:

mkdir /var/lib/phenotips/
chown tomcat:tomcat /var/lib/phenotips/

By default attached files are stored in the database, which adds limits to the maximum size of attachments allowed, and slows down performance, but keeps the backup process simpler. If you're going to upload a lot of files, or larger (more than a few megabytes) files, you can enable filesystem storage for attachments. To do this, edit webapps/phenotips/WEB-INF/xwiki.cfg and add the following lines:

xwiki.store.attachment.hint=file
xwiki.store.attachment.versioning.hint=file
xwiki.store.attachment.recyclebin.hint=file

Installing the ontology data

Download the latest solr-configuration jar, and unzip it in /var/lib/phenotips/solr/ (or if a different permanent directory was chosen in the previous step, in a solr subdirectory in the permanent directory). Make sure this directory has read-write access for the user running Tomcat, usually tomcat:

chown -R tomcat:tomcat /var/lib/phenotips/solr/

Setting up the mail server (optional)

If there is a preferred SMTP mail server installed in the institution, there is an administrative section where PhenoTips can be configured to use it. Simply go to the global administration within PhenoTips, open the Configuration -> Email section, and fill in the IP or domain name of the server, the port, and optional authentication details. If TLS encryption is required, then put mail.smtp.starttls.enable=true in the Additional JavaMail properties field.

For setting up a new mail server, Postfix is a good choice, available in most GNU/Linux distributions, and installing it is as easy as apt-get install postfix / yum install postfix / emerge postfix. Make sure it is configured to start automatically on reboot, and start it right away. PhenoTips is already configured to connect to localhost on port 25 by default, so there's no need to further edit the PhenoTips configuration.

Setting up the HTTPD frontend (optional)

While PhenoTips can run perfectly well directly from Tomcat on the 8080 port, putting a HTTPD reverse proxy in front makes it easier to configure things such as: complex access rules, HTTPS, better caching of static resources, load balancing, compressed transport, custom error messages when upgrading the PhenoTips backend, etc.

A basic setup would be:

<VirtualHost *:80>
   # Use the right hostname
   ServerName phenotips.host.name.net
   # You can add other aliases
   ServerAlias www.phenotips.host.name.net phenotips phenotips.localdomain

   # Custom logs for PhenoTips
   ErrorLog logs/phenotips.error.log
   CustomLog logs/phenotips.access.log combined
   # For Debian-based systems, use this instead:
   # ErrorLog ${APACHE_LOG_DIR}/phenotips.error.log
   # CustomLog ${APACHE_LOG_DIR}/phenotips.access.log combined

   # Disables the normal (external) proxy
   ProxyRequests Off

   # Set up access rules
   <Proxy *>
       Order deny,allow
       # You can only allow specific IP ranges instead of all
       Allow from all
   </Proxy>

   # A custom static HTML page to be displayed when PhenoTips isn't available, instead of the generic Apache 503
   ProxyErrorOverride Off
   ProxyPass /downtime/ !
   # You must provide this document
   ErrorDocument 503 /downtime/error.html

   # Enable the reverse proxy to the servlet container
   ProxyPreserveHost On
   # Certain operations, for example exports of large patient sets, can take more than the default 60 seconds allowed by the proxy; increase this further if required
   ProxyTimeout 300
   # Tomcat has an AJP connector:
   ProxyPass / ajp://127.0.0.1:8009/
   # If PhenoTips is not deployed as the ROOT application (use the correct application path):
   # ProxyPass /phenotips/ ajp://127.0.0.1:8009/phenotips/
</VirtualHost>

If you want to use HTTPS:

# For port 80, you can either use the configuration above to let the application work both with unencrypted http as well as https,
# or use this VirtualHost configuration to force redirects from http to https:
<VirtualHost *:80>
   # Use the right hostname
   ServerName phenotips.host.name.net
   # You can add other aliases
   ServerAlias www.phenotips.host.name.net phenotips phenotips.localdomain

   # Enables redirects
   RewriteEngine On
   # If the application is deployed as ROOT:
   RewriteRule ^/(.*)$  https://%{HTTP_HOST}/$1 [QSA,R=301,L]
   # If the application is not deployed as ROOT, but it is the only one on this server, you can redirect automatically to the right path with:
   # RewriteRule ^/$  https://%{HTTP_HOST}/phenotips/ [QSA,R=301,L]
   # If the application is not deployed as ROOT, and it is not the only one on this server, you must only apply the redirect to the right path prefix:
   # RewriteRule ^/(phenotips/.*)$ https://%{HTTP_HOST}/$1 [QSA,R=301,L]
</VirtualHost>

# HTTPS configuration:
<VirtualHost *:443>
   # Use the right hostname
   ServerName phenotips.host.name.net
   # You can add other aliases
   ServerAlias www.phenotips.host.name.net phenotips phenotips.localdomain

   # Enables SSL/TLS
   SSLEngine on
   SSLProtocol All -SSLv2 -SSLv3

   # Use the right path to the certificate and key
   SSLCertificateFile /etc/pki/tls/certs/server.crt
   SSLCertificateKeyFile /etc/pki/tls/certs/server.key
   SSLCertificateChainFile /etc/pki/tls/certs/server.chain.crt

   # Custom logs for PhenoTips
   ErrorLog logs/phenotips.error.log
   CustomLog logs/phenotips.access.log combined
   # For Debian-based systems, use this instead:
   # ErrorLog ${APACHE_LOG_DIR}/phenotips.error.log
   # CustomLog ${APACHE_LOG_DIR}/phenotips.access.log combined

   # Disables the normal (external) proxy
   ProxyRequests Off

   # Enable SSL support for the reverse proxy
   SSLProxyEngine on

   # Set up access rules
   <Proxy *>
       Order deny,allow
       # You can only allow specific IP ranges instead of all
       Allow from all
   </Proxy>

   # A custom static HTML page to be displayed when PhenoTips isn't available, instead of the generic Apache 503
   ProxyErrorOverride Off
   ProxyPass /downtime/ !
   # You must provide this document
   ErrorDocument 503 /downtime/error.html

   # Enable the reverse proxy to the servlet container
   ProxyPreserveHost On
   # Certain operations, for example exports of large patient sets, can take more than the default 60 seconds allowed by the proxy; increase this further if required
   ProxyTimeout 300
   # Tomcat has an AJP connector:
   ProxyPass / ajp://127.0.0.1:8009/
   # If PhenoTips is not deployed as the ROOT application (use the correct application path):
   # ProxyPass /phenotips/ ajp://127.0.0.1:8009/phenotips/
</VirtualHost>
You are responsible for obtaining a valid certificate for your host.

Save this in a file called, for example, phenotips.conf, which should be placed in the httpd configuration directory, usually /etc/httpd/conf.d, /etc/apache2/sites-enabled/ or /etc/apache2/vhosts.d/. Make sure name-based virtual hosts are enabled in the main httpd configuration file (/etc/httpd/conf/httpd.conf or /etc/apache2/httpd.conf):

NameVirtualHost *:80
# For HTTPS, also enable:
NameVirtualHost *:443
The above configuration file assumes that PhenoTips is deployed as the ROOT application, and might not work on all Linux distributions. Check out the Apache HTTPD error logs, usually found in /var/log/httpd/error_log to see any messages about errors in the configuration file. In particular, Debian requires ${APACHE_LOG_DIR}/ as the prefix for the file location instead of the logs/ directory specified in the sample configuration.

Loading the user interface

Start Tomcat using the operating system's startup method, usually /etc/init.d/tomcat restart or /etc/init.d/tomcat-7 restart. Once Tomcat finishes loading, open http://<your-server>:8080/phenotips/ (or http://localhost:8080/ if you renamed the webapp to ROOT, or just http://localhost/ if you enabled the HTTPD frontend), and the distribution wizard should appear. Follow the wizard to set up the database with the PhenoTips required documents.

User access

You can then log in, with Admin as the username and admin as the password (case sensitive). You should immediately change this default password: just click on the Administrator username displayed in the top right menu to access the user profile, and in the Preferences pane there should be a Change password button.

Troubleshooting

See the generic WAR installation instructions.