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

• If updating from lower than OpenOlat 14.0, you need to perform additional steps to update to update to log4j2
• If updating from lower than OpenOlat 15.3, you need to update your infrastructure to Tomcat 9 and Java 11. It is also mandatory that you perform the update to 15.3 before you continue updating to a more recent version. See Updating from older versions instructions.
• If upgrading to OpenOlat 17.2.x or higher, you need to update your infrastructure to Tomcat 10.1 and Java 17. Please make sure, your log4j2.xml is similar to the one shown below - it has been slightly adapted.

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:

• Java-WM: AdoptOpenJDK 17 LTS: https://adoptopenjdk.net/
• Application server: Tomcat 9: https://tomcat.apache.org/

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