Skip to content

Update guide

Updating from a previous version

This guide has been designed with our Installation Guide in mind. You should think about what data to backup if you didn't use those guides. A backup is mandatory!

It is normally no problem to skip some (major/minor) versions; an upgrade from 15.0.0 to 15.5.5 should work as well as an upgrade from 15.2.0 to 16.1.1, it will simply take more time to finish.


  • User is openolat
  • Homedirectory is /home/openolat
  • Datadirectory is ~/olatdata
  • Working directory is ~/webapp (which is a symlink to ~/openolat-x.x.x or ~/openolat_xxx)
  • Logfile directory ~/logs
  • Additional configurations are below ~/bin, ~/conf, ~/lib

Update procedure

Updating OpenOlat is generally very simple:

  1. Stop tomcat
  2. Link new release
  3. Start tomcat

In a standard configuration all necessary database modifications will be prerfomed automatically during the tomcat startup. The first start of a new release might take some time as some migration or upgrading code might run.

Follow the steps in detail:


  1. Stop Tomcat (~/stop)
  2. Backup
    • your olatdata directory
    • make a database dump
  3. Download the new openolat_xxx.war from to your ~/downloads directory
  4. Extract the openolat_xxx.war to ~/openolat-x.x.x
    unzip -d ~/openolat-x.x.x ~/downloads/openolat_xxx.war
  5. Remove link from last version to webapp
    rm ~/webapp
  6. Create symlink from new version to webapp ln -s ~/openolat-x.x.x ~/webapp
  7. If you have a custom theme, take care of updating it ~/olatdata/customizing/themes/*

Version specific update steps


  1. Start tomcat (~/start) and look at
    • Tomcat log: tail -f ~/logs/catalina.out
    • OpenOlat log: tail -f ~/logs/olat.log
    • First startup might take a while because of file and database upgrades
    • Do NOT shutdown until OpenOlat did the initial startup!
    • Look at the upgrades file and check if upgrade was successfull (set to true):
      cat ~/olatdata/system/installed_database_upgrades.xml cat ~/olatdata/system/installed_upgrades.xml
  2. Let everybody know you just updated to the newest version of OpenOlat x.x.x (Mastodon, X, facebook, etc.)

  3. Have a drink 🍺 and celebrate, but do so responsibly! ;-)

Special instructions


If you are upgrading from any version lower than 14.x.x to a version 14.x.x or higher, you will need to also upgrade from log4j to log4j2.

Here is an example for a log4j2.xml. Adapt it to your needs.

Create the file ~/lib/log4j2.xml containing the following and adapt it to your file structure and needs.

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN">
       <RollingFile name="RollingFile" fileName="/home/openolat/logs/olat.log"
                   pattern="%d{yyyy-MM-dd HH:mm:ss.SSS} [%t] %-5level %marker %c{1} ^%%^ I%X{ref}-J%sn ^%%^ %logger{36} ^%%^ %X{identityKey} ^%%^  %X{ip} ^%%^ %X{referer} ^%%^ %X{userAgent} ^%%^ %msg%ex{full,separator( )}%n" />
               <TimeBasedTriggeringPolicy interval="1" />
       <Logger name="org.apache.commons.httpclient" additivity="false" level="warn">
           <AppenderRef ref="RollingFile" />
       <Logger name="org.apache.pdfbox" additivity="false" level="fatal">
           <AppenderRef ref="RollingFile" />
       <Logger name="org.apache.fontbox" additivity="false" level="fatal">
           <AppenderRef ref="RollingFile" />
       <Logger name="org.hibernate.engine.internal.StatisticalLoggingSessionEventListener" additivity="false" level="fatal">
           <AppenderRef ref="RollingFile" />
       <!-- Change the level to debug to see the SQL statements generated by Hibernate -->
       <Logger name="org.hibernate.SQL" additivity="false" level="fatal">
           <AppenderRef ref="RollingFile" />
       <Logger name="org.hibernate.type.descriptor.sql.BasicBinder" additivity="false" level="fatal">
           <AppenderRef ref="RollingFile" />
        <Logger name="org.apache.activemq.audit" additivity="false" level="warn">
           <AppenderRef ref="RollingFile" />
       <Root level="info">
           <AppenderRef ref="RollingFile" />

Tomcat 9 and Java 11

If you are upgrading from any version lower than 15.3.x to a version 15.3.x or higher, you will need to also upgrade to Tomcat 9 and Java 11. Additionally, remove the following line from your ~/bin/

-Djava.endorsed.dirs=./common/endorsed                 \

Tomcat 10.1 and Java 17

We recommend using the following software packages:


Updating from older versions

If you have a very old system it is generally a good advice to update in steps:

  • Lower than version 10: update first to version 10
  • From version 10.0 it is safe to update straight to 15.3.x
    Note that in version 15.4 all old upgraders have been removed. Thus, when updating from a version olther than 15.3 it is mandatory to install 15.3 before you continue with the more recent versions.
  • From version 15.3 it is safe to update straight to the newest OpenOlat version