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 gernally 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 (twitter, 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>
       <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                 \

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
Back to top