This guide walks you through installing OpenOLAT on a local GNU/Linux or similar system with Tomcat8, Java8 and PostgreSQL9.

Create a user for OpenOLAT

The username is openolat in this guide with home directory in /home/openolat/. From here onwards do everything as the user openolat (unless pointed out differently).

Download OpenOLAT, JRE and tomcat

Download JRE 1.8.x, tomcat-8.x.x and OpenOLAT-x.x.x war file. Create a directory downloads and keep the downloaded files there:

openolat~$ ls -l downloads/
-rw-r--r-- 1 openolat openolat  7843733 Sep 18 10:34 apache-tomcat-8.x.x.tar.gz
-rw-r--r-- 1 openolat openolat 46808550 Sep 18 10:34 jre-xuxx-linux-x64.tar.gz
-rw-r--r-- 1 openolat openolat 85277009 Sep 10 21:42 openolat_xxx.war
Note that you do not need a JDK to run OpenOLAT.

Prepare home directory

In the home directory:

tar xvf downloads/apache-tomcat-8.x.x.tar.gz
ln -s apache-tomcat-8.x.x tomcat
tar xvf downloads/jre-xuxx-linux-x64.tar.gz
ln -s jre1.8.x_xx/ jre
unzip -d openolat-xxx downloads/openolat_xxx.war
ln -s openolat-xxx webapp

Note that this setup allows you to switch between different versions of JRE and tomcat by adjusting the symlinks jre and tomcat.

Set up tomcat in home directory

mkdir bin conf lib run logs

Link the following files

cd ~/conf
ln -s ../tomcat/conf/web.xml web.xml
cd ~/bin
ln -s ../tomcat/bin/

Create additional, handy links

cd ~
ln -s tomcat/bin/ start
ln -s tomcat/bin/ stop

Create the file bin/ containing

CATALINA_OPTS="-Xmx1024m -Xms512m -XX:MaxMetaspaceSize=512m  \                                   \
-Duser.timezone=Europe/Zurich                          \                     \
-Djava.awt.headless=true                               \                        \
-Djava.endorsed.dirs=./common/endorsed                 \
-XX:+HeapDumpOnOutOfMemoryError                        \
-XX:HeapDumpPath=.                                     \
The scripts of tomcat will parse this file at startup.

Create the file conf/server.xml

<?xml version='1.0' encoding='utf-8'?>
<Server port="8085" shutdown="SHUTDOWN">
  <Service name="Catalina">
    <Connector port="8088" protocol="HTTP/1.1" />
    <Engine name="Catalina" defaultHost="localhost">
      <Host name="localhost"  appBase="webapps" />

Make sure the chosen ports (8085 and 8088 in this example) are available.

Set the environment variables CATALINA_HOME and JRE_HOME, for example by appending the following to your .bashrc

export CATALINA_HOME=~/tomcat
export JRE_HOME=~/jre
and activate them by issuing
. .bashrc

Test tomcat


... should output something like this:

Using CATALINA_BASE:   /home/openolat
Using CATALINA_HOME:   /home/openolat/tomcat
Using CATALINA_TMPDIR: /tmp/openolat
Using JRE_HOME:        /home/openolat/jre
Using CLASSPATH:       /home/openolat/tomcat/bin/bootstrap.jar:/home/openolat/tomcat/bin/tomcat-juli.jar
Using CATALINA_PID:    /home/openolat/run/
Tomcat started.

Check whether these values make sense, then stop tomcat again


Set up postgresql database and user

This setupguide has been tested with all PostgreSQL Versions from 9.1 to 9.4. Our recommendation is to use the most recent, stable version.

Do the following as root user

su - postgres
and then as user postgres (you may need the postgresql db password, but usually not):
Now while logged in to postgresql, we create the user and the database:
create user oodbu with password 'oodbpasswd';
create database oodb with owner oodbu;

Test the account as openolat user

psql oodb -U oodbu -h localhost
You should get the postgresql client prompt after providing your password. Now create the OpenOLAT database schema, as user openolat.
psql oodb -U oodbu -h localhost
\i /home/openolat/webapp/WEB-INF/classes/database/postgresql/setupDatabase.sql

Optionally create a file named .pgpass containing

This way you can access the database by typing psql -h localhost and will connect to the right db without pw

Create OpenOLAT configuration

Create the file lib/


Create the directory conf/Catalina/localhost/ for the OpenOLAT Application context descriptor

mkdir -p conf/Catalina/localhost/
and create the file conf/Catalina/localhost/ROOT.xml containing:
<?xml version="1.0" encoding="UTF-8" ?>
<Context path="" docBase="/home/openolat/webapp" debug="0" reloadable="false" allowLinking="true">
  <Resource name="jdbc/OpenOLATDS" auth="Container" type="javax.sql.DataSource"
     maxTotal="16" maxIdle="4" maxWaitMillis="60000"
     username="oodbu" password="oodbpasswd"
     validationQuery="SELECT 1" 
Make sure the values of username, password and the "localhost:5432/oodb" part in the url value are the ones of your postgresql account for OpenOLAT.

Configure log4j2 for OpenOlat 14 and newer

Create the file lib/log4j2.xml containing

<?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" />
       <Root level="info">
           <AppenderRef ref="RollingFile" />

Configure log4j for OpenOLAT 13.x.x and older

Create the file lib/log4j.xml containing

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">
<log4j:configuration xmlns:log4j="" debug="false" threshold="all">
<appender name="CONSOLE" class="org.apache.log4j.ConsoleAppender">
  <layout class="org.apache.log4j.PatternLayout">
    <param name="ConversionPattern" value="%d [%t] %-5p %c{1} %x - %m%n"/>
<appender name="DebugLog" class="org.apache.log4j.DailyRollingFileAppender">
   <param name="File" value="/home/openolat/logs/olat.debug.log"/>
   <param name="DatePattern" value="'.'yyyy-MM-dd"/>
   <layout class="org.apache.log4j.PatternLayout">
     <param name="ConversionPattern" value="%d [%t] %-5p %c{1} %x - %m%n"/>
 <appender name="syslog" class="org.apache.log4j.DailyRollingFileAppender">
   <param name="File" value="/home/openolat/logs/olat.log"/>
   <param name="DatePattern" value="'.'yyyy-MM-dd"/>
   <layout class="org.apache.log4j.PatternLayout">
     <param name="ConversionPattern" value="%d [%t] %-5p %c{1} %x - %m%n"/>
 <logger name="org.olat"> <level value="INFO"/> </logger>
 <logger name="org.olat.basesecurity.AuthHelper"> <level value="ERROR"/> </logger>
 <logger name="org.apache.commons.httpclient"> <level value="WARN"/> </logger>
 <logger name="org.olat.core.commons.taskExecutor.ThreadPoolTaskExecutor"> <level value="ERROR"/> </logger>
 <logger name="org.apache.pdfbox.filter.FlateFilter"> <level value="FATAL" /> </logger>
 <logger name="org.apache"> <level value="ERROR"/> </logger>
 <logger name="org.hibernate"> <level value="ERROR"/> </logger>
 <logger name="org.springframework"> <level value="ERROR"/> </logger>
 <logger name="org.hibernate.event.def.AbstractFlushingEventListener"> <level value="FATAL"/> </logger>
 <logger name="net.sf.hibernate"> <level value="WARN"/> </logger>
 <logger name="org.jboss.cache"> <level value="WARN" /> </logger>
 <logger name="org.hibernate.cache"> <level value="WARN" /> </logger>
 <logger name="org.hibernate.engine.internal.StatisticalLoggingSessionEventListener"><level value="FATAL"/></logger>
 <root> <level value="INFO" /> <appender-ref ref="syslog"/> </root>

Delete the log4j.xml file packaged with OpenOLAT. The file will not be present in newer version of OpenOLAT.

rm webapp/WEB-INF/classes/log4j.xml

Start OpenOLAT


The file log/catalina.out should say

INFO: Deploying configuration descriptor /home/openolat/conf/Catalina/localhost/ROOT.xml
near the end and the last line should be like
INFO: Server startup in 16310 ms 

Try OpenOLAT

point your browser to

username: administrator
password: openolat

Happy testing!