UniTime Installation

tmtbl.custom.properties=${catalina.base}/conf/unitime.properties

• • • If the same property is defined on multiple places, the first one from the following order will be taken:

      1. UniTime Configuration (Administration / Defaults / Configuration menu item)

      2. System property (-Dproperty=value, or defined in Tomcat/conf/catalina.properties)

      3. File custom.properties (UniTime.war/WEB-INF/classes/custom.properties or as defined by tmtbl.custom.properties system property)

      4. File application.properties (UniTime.war/WEB-INF/lib/timetable.jar/application.properties)

• • Database Connection

    • • The database connection can be changed using custom properties. However, please note that these properties cannot be defined using the UniTime application (Administration / Defaults / Configuration menu item) since the database connection needs to be configured before the database can be accessed. For instance, custom.properties file can contain the following:

# MySQL Configuration Example

connection.url=jdbc:mysql://localhost:3306/timetable?serverTimezone=Europe/Prague

connection.username=timetable

connection.password=unitime

connection.driver_class=com.mysql.jdbc.Driver

dialect=org.hibernate.dialect.MySQLInnoDBDialect

tmtbl.uniqueid.generator=org.hibernate.id.TableHiLoGenerator

default_schema=timetable

• • See LDAP Authentication / Lookup page for notes about LDAP integration.

  • See Customizations page for notes about the custom styling (branding) of the UniTime application.

Remote Solver Server(s)

• • By default, all timetabling problems are solved within the application (using the same Java Virtual Machine), however, especially for bigger institutions, it might be desired to solve the timetabling problems by one or more separate solver servers.

  • All the necessary libraries are in the solver folder of the distribution except the JDBC driver. For MySQL 5.x download mysql-connector-java-5.1.49.jar, for MySQL 8.x download mysql-connector-java-8.0.32.jar ,  or for Oracle download ojdbc8.jar.

• Place the JDBC driver in the solver directory (same location as the timetable.jar), for instance:

curl https://repo1.maven.org/maven2/mysql/mysql-connector-java/5.1.49/mysql-connector-java-5.1.49.jar --output solver/mysql-connector-java.jar

• • To run a remote solver, do:

java -Xmx2g -Dtmtbl.custom.properties=custom.properties -jar solver/timetable.jar

• • File custom.properties should contain all the custom parameters needed for the starting up the server (e.g., database connection properties, if different from the defaults). It is usually the same as the one used on the Tomcat, except the jgroups.tcp.address property (see below). The load is automatically and seamlessly balanced between the remote solvers. The remote solver server also automatically reconnects itself when the web server is restarted. When the remote solver is shut down, all active timetabling instances are backed up and restored when the solver server is started again. The following properties need to be set in the custom.properties file. Please note that all these properties need to be set on the Tomcat side as well.

jgroups.tcp.address=127.0.0.1

IP address of the machine that is using this configuration file. This property should be different on each machine; the remaining properties are usually the same for all the UniTime instances (Tomcats as well as remote solver servers). If the property is set to 127.0.0.1 or localhost, the server will not be able to accept remote connections -- use only if all the instances are running on the same machine!

unitime.solver.cluster=true

This property enables the Solver cluster. This cluster is used for RPCs between the Tomcat(s) and the remote solver server(s). Communication between UniTime instances is done using JGroups.

unitime.solver.port=7800

Default communication port for the Solver cluster. If the given port is taken (e.g., there are running multiple remote solver server(s) on the same machine), the next one available will be used instead.

unitime.solver.initial_hosts=127.0.0.1[7800]

By default, TCP ping discovery is used to form a cluster. The above parameter defines a comma-separated list of machines (and their communication ports) on which a UniTime instance may be running. It does not necessarily need to have all the possible IP addresses; usually, it is set to the IP addresses of the Tomcat server(s) running UniTime.

unitime.solver.jgroups.config=solver-jgroups-tcp.xml

An alternative JGroups configuration file can be provided with this property. The default configuration file is available here.

unitime.enrollment.server.replicated=false

This property enables the replication of online student scheduling servers. If enabled, there is an additional Enrollment cluster is formed, and the same instance (academic session) of an online student scheduling server can be spawned by each of the servers (with the data replicated among them). By default, one of them will be elected as master and handle all the updates, while the others will assist in no-updating queries (e.g., computation of a student's schedule or suggestions) and step in in case of a failover. It is also possible to direct particular academic sessions to particular UniTime instances (Tomcats or remote solver servers) using the unitime.enrollment.term, unitime.enrollment.year, unitime.enrollment.campus properties (containing a regular expression that has to match against academic session term, year, and initiative, respectively).

unitime.enrollment.port=7866

If online student scheduling server replication is enabled, an additional Enrollment cluster is formed. It is used to replicate data between online student scheduling instances. This is the communication port for the Enrollment cluster.

unitime.enrollment.initial_hosts=127.0.0.1[7866]

List of initial hosts for the Enrollment cluster.

unitime.enrollment.jgroups.config=sectioning-jgroups-tcp.xml

An alternative JGroups configuration file can be provided with this property. The default configuration file is available here.

• The remote solvers can be managed in the UniTime application; see Administration > Solver > Manage Solvers menu item when logged in as an administrator.

• Tip:  If you use a different version of the JDBC driver, it needs to be added to the classpath. For example:

java -Xmx2g -Dtmtbl.custom.properties=custom.properties -cp solver/timetable.jar:solver/mysql-connector-java-5.1.46.jar org.unitime.timetable.solver.jgroups.SolverServerImplementation

Having Multiple Tomcats (Clustering)

With UniTime 4.0, it is possible to run multiple instances of UniTime on a cluster of Tomcats and/or remote solver servers. Besides the Solver cluster and Enrollment cluster, it is also possible to form a Hibernate cluster that is used to replicate Hibernate L2 cache. The following properties can be used to configure the Hibernate cluster.

unitime.hibernate.cluster=true

This property enables the Hibernate cluster. This cluster is used for replication of Hibernate second level cache between multiple UniTime instances.

unitime.hibernate.port=7833

Default communication port for the Hibernate cluster. If the given port is taken (e.g., there are running multiple remote solver server(s) on the same machine), the next one available will be used instead.

unitime.hibernate.initial_hosts=127.0.0.1[7833]

By default, TCP ping discovery is used to form a cluster. The above parameter defines a comma-separated list of machines (and their communication ports) on which a UniTime instance may be running. It does not necessarily need to have all the possible IP addresses; usually, it is set to the IP addresses of the Tomcat server(s) running UniTime.

unitime.hibernate.jgroups.config=hibernate-jgroups-tcp.xml

An alternative JGroups configuration file can be provided with this property. The default configuration file is available here.

Please note that Hibernate cluster is only needed when there are two or more Tomcats running UniTime. Remote solver servers have the L2 cache disabled and hence no need to connect to the Hibernate cluster.

Using Oracle Database

Here are some notes about using Oracle Database

• • The following custom properties need to be set (connection URL, username, and password may vary)

# Oracle Configuration Example

connection.url=jdbc:oracle:thin:@localhost:1521:xe

connection.username=timetable

connection.password=unitime

connection.driver_class=oracle.jdbc.driver.OracleDriver

dialect=org.hibernate.dialect.Oracle10gDialect

tmtbl.uniqueid.generator=org.hibernate.id.SequenceGenerator

• • If the schema is different from timetable, the default_schema property needs to be changed as well

default_schema=timetable

• • File ojdbc7.jar (or later) needs to be copied either to Tomcat/lib or to Tomcat/webapps/UniTime/WEB-INF/lib. This file can be downloaded, e.g., from Oracle JDBC Drivers

  • Oracle installation scripts are located in doc/oracle folder of the distribution

    • Alternatively, the database can be imported using imp tool and the woebegon.dat from the GitHub.

imp timetable/###### file=woebegon.dat full=y

• • • User timetable needs to be created first, e.g., using sqlplus

sqlplus system

create user timetable identified by ######; grant dba to timetable; exit

Using PostgreSQL

Here are some notes about using PostgreSQL, for more details, please see the Migrating to PostgreSQL document.

• Install PostgreSQL 12.0 or later from https://www.postgresql.org/download (using the default port 5432, and a custom password)

  • Create timetable user and timetable database, using the same name and credentials as the default UniTime database:

createuser --interactive --pwprompt -U postgres

Enter name of role to add: timetable

Enter password for new role: unitime

Enter it again: unitime

Shall the new role be a superuser? (y/n) n

Shall the new role be allowed to create databases? (y/n) y

Shall the new role be allowed to create more new roles? (y/n) n

Password: <password provided during install>

createdb timetable -U timetable -O timetable

Password: unitime