PhenoTips » Administration Guide » PhenoTips Installation Instructions

PhenoTips Installation Instructions

PhenoTips Installation Instructions

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.

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

More detailed instructions for this configuration are available.

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, the servlet container, the database engine, and the (optional) frontend server and mail server.

Installing the application

For good performance, PhenoTips requires more memory than most servlet containers allocate by default, so the startup configuration must be updated with custom -Xmx and -XX:MaxPermSize parameters. At least -Xmx1024m -XX:MaxPermSize=256m is recommended, but some enterprise-level containers already consume a lot of resources, so more should be allocated. If you have a more powerful server, feel free to increase the -Xmx parameter even further.

Download the latest PhenoTips WAR distribution and deploy it. If the container doesn't allow making changes to the configuration files inside the WAR file, then you should unzip it first, make all the changes required in the following steps, re-zip it back into phenotips.war, then deploy the configured application.

Make sure the user running the servlet container has read access on all the application files.

Setting up the database

PhenoTips already comes bundled (and configured) with a lightweight, but highly performant database engine — HSQLDB. If you're happy with this default database, then there's nothing left to do, skip to the next section.

You will have to create a database and grant all access to a user of your choice. Remember the database name, user name, and password. The PhenoTips application will take care of the table creation itself. Some database systems use schemas instead of databases, so create a schema instead.

The default application only includes the database connectors for MySQL and HSQLDB, so for other database systems you have to include the required connector. Simply download and place the connector into WEB-INF/lib/ in the phenotips application.

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

   <property name="connection.url">jdbc:mysql://localhost/phenotips</property> <!-- Replace phenotips with the chosen database name, and the database engine type in the URL -->
   <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 -->

You must also edit 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 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 the servlet container.

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 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 solr-configuration jar that matches the PhenoTips version you are installing, 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 recursive read-write access for the user running the servlet container.

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 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
   # For containers that have 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/
   # For containers that only support http (use the correct port):
   # ProxyPass / http://127.0.0.1:8080/
</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
   # For containers that have 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/
   # For containers that only support http (use the correct port):
   # ProxyPass / http://127.0.0.1:8080/
   # RequestHeader set X-Forwarded-Proto "https"
</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 the servlet container using the operating system's startup method. Once it 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

Application not deployed

Check the Java version actually being used. PhenoTips currently requires at least version 1.7 of the Java Runtime, and will fail to start when running with 1.6 or lower. Although the java -version command might report version 1.7, the servlet container might use a different version, since it has its own way of finding a java command to run. On Linux-like systems, you can run ps aux and look for the java process running the servlet container, which should include a full path to the executable, and execute that full path to see which version it is.

Big error stacktrace displayed when loading PhenoTips in a browser

The most frequent cause is a wrong connection to the database, either wrong username/password, wrong connection URL, or, if it's not HSQLDB or MySQL, missing database connector.

In general, the top of the stacktrace is not relevant. The proper way to read a stacktrace is to look from the bottom up, looking for the unindented Caused by... lines, starting with the last one. The real cause of the error should be near the end.

Distribution wizard not showing up

If the application starts correctly, but all you see is a The requested document could not be found message, then the distribution wizard, which is supposed to finish installing the required database files, failed to execute. There are two likely causes for this:

  • There is a wrong setting in <permanentDirectory>/jobs/ or <permanentDirectory>/extension/, try deleting those directories
  • The servlet container can't access <webappDirectory>/META-INF/maven/org.phenotips/phenotips-war/pom.xml, check the access rights on that file and on all its parent directories.

Broken interface after the distribution wizard finished installing the application

Try restarting the servlet container.

Distribution wizard showing up after each server restart

The most likely cause is that the permanent directory is not configured, or the configured directory isn't writable by the user running the servlet container. Check the value specified in WEB-INF/xwiki.properties, as mentioned in the Configuring PhenoTips section, and check the access rights on that directory with stat /var/lib/phenotips (use the right directory name). Without a properly configured permanent directory where the application can write its state, a temporary directory will most likely be used, and temporary directories are usually wiped out during restarts.