TOMUSS install

This page provide step to step explanations to install and customize TOMUSS version 5.2.3. It does not replace the reference documentation.

It is a bit complicated because TOMUSS is not an integrated application. You must integrate it in your own information system.

Beware: TOMUSS does not support copy past of multiple cells because it is a source of errors. Read the documentation to see how to import data.

Requirements

To run, you needs:

On Debian and derivatives, you can install theses requirements with the following command:
sudo apt-get install inkscape gettext python python-ldap python-imaging git

A web server is not required.

Getting the sources

To get the last version, run these shell commands:

wget http://perso.univ-lyon1.fr/thierry.excoffier/TOMUSS/tomuss.tar.bz2
bzcat tomuss.tar.bz2 | tar -xvf -
cd TOMUSS-*

TOMUSS is now installed!

All the following commands and file names assumes your current directory is TOMUSS one.

Verify installation

Run the regression test once to verify if TOMUSS is working.

make regest1

It should display after one minute or two: Test fine

If the test fails, run it once more, it may happen.

Testing installation

You needs to initialize localization:

make translations

And launch TOMUSS server:

./tomuss.py regtest

Many messages are displayed because TOMUSS is in debug mode. The prompt does not come back until the server is killed. To verify if it is working correctly, follow the following URL: http://127.0.0.1:8888/=super.user

On the web interface, enter the letter 'a' in UE search box, and click on a UE title. The table are all empty, because TOMUSS is not yet customized. You can play with it, but it is preferable to customize basic things.

BEWARE: with 'regtest' parameter, there is no authentication. So everybody may see and modify TOMUSS content.

TOMUSS customization

Configurations explanations are from the most critical to the less important.

User information

User information is critical because it is needed to sort teachers and students.

Getting information

The information are retrieved via LDAP protocol, but it is easily modifiable.

Edit the config table : http://127.0.0.1:8888/=super.user/0/Dossiers/config_table

Modify the most important lines:

To avoid any problem, restart TOMUSS and reload web pages. To test if it is working, you can:

The information you entered in tables is stored in DBregtest

Sorting users roles

Edit the ACLS table : http://127.0.0.1:8888/=super.user/0/Dossiers/config_acls

This table define a tree of user groups. You should add the new lines to define more leaves:
MemberGroup
your-own-loginroots
ldap:CN=all-the-teachers...DC=...teachers
ldap:CN=all-the-students...DC=...students
python:lambda x: x[-1].isdigit()students
python:lambda x: not x[-1].isdigit()teachers

The 2 last lines sort the teachers and students from the last character of the login.

Authentication

TOMUSS currently support only 2 methods of authentication, the best is to use a CAS (Centralized Authentication Service)

CAS

Edit the file LOCAL/config.py. You will find in it: configuration.cas = 'https://cas.domain.org/cas'

Set configuration.cas to the URL of your CAS server.

Unix passwords

In this case, a web server is required as a frontend to do the authentication.

Edit the file LOCAL/config.py. You will find in it: configuration.cas = 'https://cas.domain.org/cas'

Replace it with configuration.cas = ""

You must use https because passwords are not crypted by the basic authentication method.

Here an example of .htaccess you must use to force users to authenticate with the web server. The web server redirect request on port 80 on the TOMUSS server port 8888 on the local host.

AuthBasicProvider file
AuthType Basic
AuthName "Your Identifiants"
AuthUserFile /etc/apache/passwd
 
# Set the allow/deny order
Order Deny,Allow

# Indicate that any of the following will satisfy the Deny/Allow
Satisfy any

# First off, deny from all
Deny from all

# or require a valid user
Require valid-user
 
RewriteEngine on
RewriteRule ^(.*) http://127.0.0.1:8888/$1 [P]

Switch to authenticated

Once an authentication method is defined, you kill the TOMUSS server and relaunch it without the 'regtest' parameter. to prevent any problems between server running without or with authentication the data is not stored at the same place. So a copy must be done.

killall tomuss.py
if [ ! -d DB ]
    then
    cp -a DBregtest/. DB
    fi
./tomuss.py

Mails

TOMUSS send mails to contacts when there is a problem. It also manages students mass mailing. These configurations are indicated in http://127.0.0.1:8888/0/Dossiers/config_table

Sending mails

The default smtpserver host is 127.0.0.1 If there is no SMTP server on your computer, replace this value by the name of an SMTP server. To not lost any mail you may indicate 2 SMTP servers as smtp1.foo.org smtp2.foo.org

Contacts mail

The maintainer define both the contact mail displayed to the users and the address receiving the alerts when the server has a problem.

Courses

It is possible to let teachers define the courses list and the student list. But these information are yet defined in your information system, so let TOMUSS take it.

Students list

If the students list are in LDAP. You indicate in the configuration table the values for ou_ue_starts. The students found in the LDAP group will be added in the good table.

You can also redefine your own access method for student lists. In LOCAL/config.py you can add this:

from .. import inscrits

class MyLDAP(inscrits.LDAP):
    def students(self, ue, year=None, semester=None):
        # The following code must use 'ue' to find students
	# Year and Semester are the ones of the table to fill or update
        for i in range(5):
            yield ('login%d' % i,     # The login (as in LDAP)
                   'firstname%d' % i,
                   'surname%d' % i,
                   'mail%d' % i,
                   'g%d' % i,         # A group information
                   's%d' % i)         # A sequence information
	# For this student, search names and mail in LDAP:
	yield ("k10", "", "", "", "gX", "SY")

inscrits.LDAP = MyLDAP

After restarting TOMUSS server, you can visit any table an you will find 5 students: http://127.0.0.1:8888/2008/Test/UE-foobar

The firstname, surname, mail are indicated in this function in case they are not found in the LDAP.

Courses list

In LOCAL/config.py you can add this to create your own list or courses with their title and managers:

from .. import teacher

def get_ue_dict():
  ues = {}
  for i in range(1,10):
    ue_code = "My-UE-%d" % i
    ues[ue_code] = teacher.UE(
        ue_code,                   # UE Name
        ['MFirstname MSurname',],  # The names of the UE managers
        u'UE%d Title' % i,         # UE title
        [],                        # DEPRECATED: Departments of UE
        1000+i,                    # A key for an external Database
        ['ue%d.master' % i,],      # Login of teachers
        1,                         # DEPRECATED: #students registered
        0,                         # DEPRECATED: #students EC registered
        ['ue%d_test@test.org' % i],# Teachers mails
        2000+i,                    # Another key for an external Database
        )
  return ues

teacher.get_ue_dict = get_ue_dict

Once it is done, you must run the following command to create the TOMUSS database of UE.

(cd LOCAL ; make)

After TOMUSS server restart, you will find your UE on the home page.

The names and mails of manager are not required if they can be found into LDAP using their logins.

Student pictures

Two possibles way to display pictures.

By an external service

If you have a service sending the picture of a student from its login, then make TOMUSS use this service by adding to LOCAL/config.py

def picture(student_id, ticket):
    return 'http://webservice.my.org/picture?id=' + student_id + '.png'
configuration.picture = picture

By TOMUSS itself

Just copy all the pictures in the PICTURES directory with the names: login.JPG

If it is not possible to change picture encoding or name, make your own version of PLUGINS/picture.py

Year and semester

Most of the TOMUSS URL start by Year/Semester and by default, only one semester allows modifications. This semester is defined by the variable year_semester of the configuration table.

Beware: the year is the real calendar year, it is not the university year.

The default TOMUSS configuration assume that each university year is splitted into 2 semesters, the first one starts in august (Automn), the second one starts in February (Spring). In LOCAL/config.py it is defined as:

set_semesters(
    ('Printemps', -1, [2, 7], '#EEFFEE' ),  # Spring (Semester 2)
    ('Automne'  ,  0, [8,13], '#FFE8D0' ),  # Autumn (Semester 1)
    )

So the university semesters for the year 2012-2013 are:

If you want to create your own semesters:

for SEMESTER_NAME in Automn Spring Grades
do
  echo 'from ...TEMPLATES.Printemps import *' \
       >LOCAL/LOCAL_TEMPLATES/$SEMESTER_NAME.py
done

Beware: indicate a new set_semesters in LOCAL/config.py and modify year_semester in the configuration table.

Il you have no semesters in your university, you can indicate (if Grades.py was created):

configuration.set_semesters(
    ('Grades', 0, [8, 20], '#EEEEEE' ),
    )

Semesters history

The content of semesters in history is displayed to students using 'suivi' servers.

A list of manager year/semester to display must be defined, by default, the semester of the calendar year are defined in LOCAL/config.py:

# Add a server for each semester of the current year.
# You must redefine this to enumerate the semester in use.
for i, semester in enumerate(configuration.semesters):
  configuration.suivi.add(
    time.localtime()[0],      # The current Year
    semester,                 # A semester
    socket.getfqdn() + ':%d', # The user visible URL for the 'suivi' server
    8889 + i)                 # The socket port number of the server

It is easier to manage a simple enumeration:

configuration.suivi.add(2013,"Autumn","https:tomusss.my.org",8889)
configuration.suivi.add(2013,"Spring","https:tomusss.my.org",8890)

If CPU power is not a problem, it is possible to indicate the same socket port number for all the 'suivi' servers. It will use less memory.

Using 'suivi' servers

Enter some grades into a couple of TOMUSS table.

Start all the 'suivi' servers (and TOMUSS server):

make

See the 'suivi' of a student by one of the following methods:

Other makefile goal are useful : stoptomuss, stopsuivi, restartsuivi,

TOMUSS administration

Once installed, it runs alone. Some administrative actions are displayed to the roots users on the right column on the home page.

Recurrent job

Use crontab to schedule some tasks.

5 minutes job

It is a good idea to run SCRIPTS/crontab_run.py crontab every five minutes. This script relaunch stalled servers, or launch TOMUSS servers if the computer has rebooted.

Hourly backup

Just to be on the paranoiac side, an hourly backup of the data is a good idea:

rsync --archive --no-g --delete --exclude '*.pyc' DB/. Distant_Location

Night job

It is a good idea to run SCRIPTS/night_job every night. The log of the work is stored in LOGS directory. The script does the following things:

Upgrade

for a simple and secure upgrade:

If there is a problem found after that, you can stop the new servers and restart the old ones. They are working on the same files.

Lost data

It is really hard to lose data with TOMUSS:

These 2 restorations are only manual, not automatic.