PhenoTips » Administration Guide » Upgrading PhenoTips

Upgrading PhenoTips

Upgrading PhenoTips

These instructions are valid for a server running GNU/Linux, with PhenoTips running under Tomcat 7.
Always backup the data before any upgrade!

PhenoTips is built as a wiki application on top of the XWiki Platform. So, the upgrade consists of two parts: upgrading the platform on the server and upgrading the wiki documents from a browser.

Backing up the data

  1. Save the contents of /var/lib/phenotips/ and /var/lib/tomcat*/webapps/
  2. Backup the database.
    • For the embedded hsqld database distributed in the standalone package or the RPM, this is already included in /var/lib/phenotips/ so the previous step is enough
    • For mysql, use mysqldump --events --single-transaction $MDB -u $MUSER -p$MPASS -h $MHOST > /var/lib/phenotips/backup/database-`date +%Y%m%d`.sql (replace $MDB with the name of the database, $MUSER with the name of the mysql user, $MPASS with the password, and $MHOST with the hostname of the server where the database server runs, usually localhost)
  3. Save the contents of /var/lib/tomcat*/webapps/

Upgrading the platform

This involves changes on the server's filesystem, so all operations must be executed on the server.

  1. ssh to the server as root (or sudo su)
  2. Stop the tomcat service, for example systemctl stop tomcat || service tomcat stop
  3. mkdir -p /var/lib/phenotips/next
  4. cd /var/lib/phenotips/next
  5. Download the standalone package corresponding to the version you want to install, for example:
    curl -o 
  6. unzip phenotips-*.zip && rm phenotips-*.zip
  7. cd phenotips-*
  8. rm -rf ../../solr/ && cp -r data/solr ../../
  9. mkdir /var/lib/phenotips/backup
  10. mv /var/lib/tomcat*/webapps/phenotips /var/lib/phenotips/backup or mv /var/lib/tomcat*/webapps/ROOT /var/lib/phenotips/backup if deployed as the root webapp
  11. mv webapps/phenotips /var/lib/tomcat*/webapps (rename to ROOT if the application was previously deployed as the root webapp)
  12. rm -rf /var/lib/phenotips/next
  13. Merge any custom changes done in the following configuration files from the old instance into the new one:
    1. xwiki.cfg
    3. hibernate.cfg.xml
  14. chown -R tomcat7:tomcat7 /var/lib/phenotips || chown -R tomcat:tomcat /var/lib/phenotips
  15. Start the tomcat service, for example systemctl start tomcat || service tomcat start

Upgrading the application documents

  1. Open the PhenoTips instance in a browser
    • Since the last step from the platform upgrade restarted the server, it might take a minute or two for the application to respond
  2. Login as a user with administrative rights
  3. The Distribution Wizard should appear; if it doesn't, replace the URL path (the part after the server name) in the browser's address bar with /bin/distribution/
  4. Click on the Continue button next to the PhenoTips - Application interface item
  5. Again
  6. Wait for all the documents to be updated
    • If any "conflicts" are reported, just click Continue
  7. Once it finishes, click the Continue button in the bottom right corner of the dialog
  8. The upgrade should be done now

Updating a standalone copy of PhenoTips

  1. Get a new standalone version, unzip it
  2. Delete its "data" directory
  3. Copy the "data" directory from the old instance
  4. Start the new instance
  5. Log in with an administrative account (by default user Admin, password admin)
  6. Follow the onscreen "distribution wizard"


PhenoTips® is freely available under the terms of the the GNU Affero General Public License, version 3.0.

 Download the latest release
 Play with our demo
 Get the source code


 Ask for free support (by volunteers):
 Inquire about commercial support:
 Follow us on twitter:

PhenoTips® is an exclusive trademark of Gene42 Inc.