Timetabling Installation

From UniTimeWiki

Jump to: navigation, search

Contents

Prerequisites

Java Development Kit

  • If you do not have Java SE (Standard Edition) Development Kit 5.0 or later already installed, you will need to download and install it from Java SE Downloads first.
    • UniTime 3.2 requires Java SE 6.0 or later

Apache Tomcat

MySQL

  • Download MySQL from MySQL Downloads
    • MySQL version 5.1 and Oracle version 10g are currently being used in development and testing.
    • Alternatively, you can use Oracle or other SQL-enabled database. See Hibernate Supported Databases for more details.
  • Install MySQL
  • On Lynux based systems, MySQL is case sensitive on table names by default. To change this, add the following line to the /etc/my.cnf file. This forces MySQL to translate all table names to lowercase before executing the statement. 
lower_case_table_names=1


Installation

  • Download the latest UniTime distribution from UniTime Downloads
    • All distributions are platform independent, distributed in either .zip or .tar.gz format
    • Alternatively, you can download the most recent nightly build from UniTime Nightly Builds
  • Unzip the archive 
tar -xvzf unitime-3.1_bld270.tar.gz
  • Install timetable database
    • MySQL installation scripts are located in doc/mysql folder of the distribution
    • File schema.sql contains the database schema, file woebegon-data.sql contains test data (Woebegon College Test Suite, see Online Demo for more details).
      • If you want to change the default user name / password, edit the file schema.sql first. The user is created at the very beginning of the script.
      • If you are using MySQL 4.1, you might need to create the user differently. To do so, uncomment the MySQL 4 part of the file and comment out the MySQL 5 part of the file
        • Line drop user timetable; might need to be commented out when the script is executed on MySQL 5 for the first time. 
-- MySQL 5:
drop user timetable;
create user timetable identified by 'unitime';
grant all on timetable.* to timetable;
flush privileges;

-- MySQL 4
/*
delete from user where user='timetable';
insert into user (host,user,password) values ('%', 'timetable', password('unitime'));
grant all on timetable.* to timetable;
flush privileges;
*/
  • Timetable database can be created and populated using the mysql command line tool
    • After running "schema.sql", you need to populate the database either using "woebegon-data.sql" or "blank-data.sql" file
      • When woebegon-data are used, you will be able to login into the application using the same credentials as described on our online demo page.
      • When blank-data are used, there is only administrator account created. Both user name and password are admin. 
mysql -uroot -p -f <schema.sql
mysql -uroot -p <woebegon-data.sql
  • Deploy UniTime application
    • Copy web/UniTime.war to ${TOMCAT_HOME}/webapps, where ${TOMCAT_HOME} is the folder where Tomcat is installed.
  • On unix based systems (including Mac OS X), java virtual machine that is running tomcat needs to be switched to headless mode. You can do that using JAVA_OPTS environment variable prior to starting tomcat: 
 export JAVA_OPTS="${JAVA_OPTS} -Djava.awt.headless=true"
  • Also, you might need to give Tomcat more memory to work with by changing the upper limit on the memory that it can allocate (especially if you are planning not to run any remote solver servers -- see below; default is 64MB). You can do that using JAVA_OPTS environment variable as well: 
 export JAVA_OPTS="${JAVA_OPTS} -Xmx512m"
  • If you are running tomcat using tomcat.exe, the option is --JvmMx 512. If you are running tomcat as a windows service, you may need to run something like tomcat6 //US//Tomcat6 --JvmMx 512 to update the memory settings -- see Windows service HOW-TO for more details.
  • Start tomcat

Upgrade

  • To upgrade an existing UniTime installation, only the new UniTime.war file should be placed in the ${TOMCAT_HOME}/webapps folder instead of the existing one. All the necessary changes to the database are done automatically during the first deployment. The most safe way to do so is as follows:
    1. Stop tomcat
    2. Backup the existing database (e.g., using mysqldump on MySQL or exp on Oracle)
    3. In ${TOMCAT_HOME}/webapps, remove UniTime folder and replace the existing UniTime.war with the new one
    4. Start the tomcat
  • If you are using remove solver servers, the appropriate JARs needs to be updated as well.


Customization

  • Custom Properties
    • There are a lot of properties that are defined in file application.properties that is located in timetable.jar that is located in UniTime.war at WEB-INF/lib. These properties can be changed in one of the following ways:
      1. By providing custom property file, this file should be named custom.properties and located in UniTime.war at WEB-INF/classes.
        • Alternatively, custom property file can be located somewhere else, with system property tmtbl.custom.properties pointing to it.
      2. By adding and/or changing the appropriate properties directly in the UniTime application -- see Administration / Defaults / Configuration menu item when logged in as administrator.
      3. By adding these properties in ${TOMCAT_HOME}/conf/catalina.properties
      4. By providing JVM that is running tomcat with the appropriate system properties, for instance:
    • 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_HOME}/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) 
export JAVA_OPTS="${JAVA_OPTS} -Dtmtbl.title=Timetabling Demo"
export JAVA_OPTS="${JAVA_OPTS} -Dtmtbl.custom.properties=~/my.properties"
  • Database Connection
    • Database connection can be either changed in hibernate.cfg.xml that is located in timetable.jar that is located in UniTime.war at WEB-INF/lib or using custom properties (see above). Properties (re)defined using custom properties take precedence.

Connection properties in hibernate.cfg.xml: 

<!-- MySQL Configuration -->
<property name="connection.driver_class">com.mysql.jdbc.Driver</property>
<property name="connection.url">jdbc:mysql://localhost:3306/timetable</property>
<property name="connection.username">timetable</property>
<property name="connection.password">unitime</property>
<property name="dialect">org.hibernate.dialect.MySQLInnoDBDialect</property>
<property name="tmtbl.uniqueid.generator">org.hibernate.id.TableHiLoGenerator</property>
<!-- End of MySQL Configuration -->

Or, 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: 

 # MySQL Configuration Example
 connection.url=jdbc:mysql://localhost:3306/timetable
 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


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. To run a remote solver, do: 

java -Xmx1024m -jar solver/timetable.jar host:9998

or 

java -Xmx1024m -jar solver-min/solver.jar host:9998

Parameter host is the name of the machine where the web server is executed. The difference between the two distributions is that solver-min contains only the necessary classes to connect to the web server. The rest are downloaded using a special class loader. Communication between the web server and the solver server is done using SLL. The solver servers also communicate directly with the database for loading input data and saving the solution. Database connection properties are taken from the web server. 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 can be defined (and passed as system properties):

tmtbl.solver.register.port
web server listens on this port for all remote solvers to connect (same port needs to be defined on both sides, default is 9998)
tmtbl.solver.remote.port
a remote solver accepts commands on this port, during start up it binds itself on this port or on the first available port after this port (default is 1200)
tmtbl.solver.register.host
host name of the web server (default is localhost)
tmtbl.solver.home
directory where the remote solver will put its files (logs, backuped or passivated problem instances, etc.)
tmtbl.custom.properties
location of custom property file (see above)

Example: 

java -Xmx1024m -Dtmtbl.solver.home=~/solver -jar solver-min/solver.jar host:9998

The remote solvers can be managed in the UniTime application, see Timetables / Manage Solvers menu item when logged in as an administrator.

Using Oracle Database

Here are some notes about using Oracle Database

  • The following custom properties needs to be set (connection url, username, 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.OracleDialect
tmtbl.uniqueid.generator=org.hibernate.id.SequenceGenerator
default_schema=timetable
  • If the schema is different than timetable, the default_schema property needs to be changed
  • File ojdbc5.jar (or later) needs to be copied either to ${TOMCAT_HOME}/common/lib (if Tomcat 5 is used, where ${TOMCAT_HOME} is the folder where Tomcat is installed), ${TOMCAT_HOME}/lib (it Tomcat 6 is used), or inside UniTime.war at WEB-INF/lib. This file can be downloaded, e.g., from Oracle10g JDBC Drivers
    • When using UniTime 3.2 set the dialect to Oracle10gDialect 
dialect=org.hibernate.dialect.Oracle10gDialect
  • Oracle installation scripts are located in doc/oracle folder of the distribution


Deployment on JBoss AS

The UniTime application can be deployed on JBoss Application Server or, in theory, on any other J2EE server.


Back to Timetabling Project Page.

Retrieved from "http://wiki.unitime.org/Timetabling_Installation"
Personal tools