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.

Assumptions

  • 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:

Preparation

  1. Stop Tomcat (~/stop)
  2. Backup
    • your olatdata directory
    • make a database dump
  3. Download the new openolat_xxx.war from https://www.openolat.com/releases/ 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

Update

  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

log4j2

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">
   <Appenders>
       <RollingFile name="RollingFile" fileName="/home/openolat/logs/olat.log"
           filePattern="/home/openolat/logs/olat.log.%d{yyyy-MM-dd}">
           <PatternLayout
                   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" />
           <Policies>
               <TimeBasedTriggeringPolicy interval="1" />
           </Policies>
       </RollingFile>
   </Appenders>
   <Loggers>
       <Logger name="org.apache.commons.httpclient" additivity="false" level="warn">
           <AppenderRef ref="RollingFile" />
       </Logger>
       <Logger name="org.apache.pdfbox" additivity="false" level="fatal">
           <AppenderRef ref="RollingFile" />
       </Logger>
       <Logger name="org.apache.fontbox" additivity="false" level="fatal">
           <AppenderRef ref="RollingFile" />
       </Logger>
       <Logger name="org.hibernate.engine.internal.StatisticalLoggingSessionEventListener" additivity="false" level="fatal">
           <AppenderRef ref="RollingFile" />
       </Logger>
       <!-- 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>
       <Logger name="org.hibernate.type.descriptor.sql.BasicBinder" additivity="false" level="fatal">
           <AppenderRef ref="RollingFile" />
       </Logger>
        <Logger name="org.apache.activemq.audit" additivity="false" level="warn">
           <AppenderRef ref="RollingFile" />
       </Logger>
       <Root level="info">
           <AppenderRef ref="RollingFile" />
       </Root>
   </Loggers>
</Configuration>

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/setenv.sh:

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

Tomcat 10.1 and Java 17

We recommend using the following software packages:

Tomcat 10.1.42 and greater

Tomcat 10.1.42 changed the behavior of the number of parameters that can be submitted by the browser by default. This new defaults break OpenOlat when using the standard Tomcat HTTP connector.

In your server.xml make sure you set maxPartCount and maxParameter to indefinite (-1).

<Connector port="8088" protocol="HTTP/1.1" maxPartCount="-1" maxParameterCount="-1" />

Troubleshooting

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