wget https://perso.univ-lyon1.fr/thierry.excoffier/TOMUSS/run chmod 755 run mkdir TOMUSS cd TOMUSS ../run # To configure and launch # ../run regtests # To run regression tests # ../run try # To run without authentication and animals (k01...)
This page provide step to step explanations to install and customize TOMUSS version 7.0.0. 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.
To run, you needs:
wget https://perso.univ-lyon1.fr/thierry.excoffier/TOMUSS/tomuss-docker-bare.tar.gz -O - |
zcat | docker load
apt update
apt install catdoc espeak gettext git gnuplot graphviz inkscape iotop \
ipython3 libaio1 locales make mypy netpbm nginx nodejs poppler-utils \
pylint3 pylint python-setuptools python3-cffi python3-coverage \
python3-dev python3-ldap python3-matplotlib python3-networkx \
python3-pil python3-pip python3-pyclamd python3-pyinotify \
python3-pypdf2 python3-qrcode python3-reportlab python3-setuptools \
python3-xlsxwriter rsync strace unzip wget xlsx2csv \
python3-selenium firefox-geckodriver chromium-chromedriver \
xnest xvfb i3 # Last 2 lines are for regression testing
apt upgrade
ln -s /usr/share/zoneinfo/Europe/Paris /etc/localtime # For regression tests
apt install locales
echo 'export LC_ALL=C.UTF-8' >>/etc/profile
echo 'export TZ=Europe/Paris' >>/etc/profile
echo 'en_US.UTF-8 UTF-8' >/etc/locale.gen
echo 'fr_FR.UTF-8 UTF-8' >>/etc/locale.gen
locale-gen
. /etc/profile # The server must run with UTF-8 enabled
A web server is not required for testing. In production, one is needed to add HTTPS and to offload static files serving.
To get the last version, run these shell commands:
git clone https://git.code.sf.net/p/tomuss/code tomuss-code cd tomuss-code if [ ! -d LOCAL ] then # Only to run regression tests. Create your own LOCAL directory # with all your customizations and new functionnalities. ln -s LOCAL.template LOCAL fi
TOMUSS is now installed!
All the following commands and file names assumes your current directory is TOMUSS one.
Run the regression test once to verify if TOMUSS is working.
make regtest1
It should display after 5 minutes: Test fine
If the test fails, run locale and verify if the character encoding is UTF-8.
Never run regression tests on production server, they are destructive.
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:
****************************************************************************** First time TOMUSS user, goto : http://172.17.0.3:8888/=super.user Type 's' in the UE search box. Type 'a' in the student search box. You can start some 'suivi' servers : ./suivi.py 2020 Automne 8890 regtest ./suivi.py 2020 Printemps 8889 regtest ******************************************************************************
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.
Configurations explanations are from the most critical to the less important.
User information is critical because it is needed to sort teachers and students.
The information are retrieved via LDAP protocol, but it is easily modifiable.
Edit the config table, the link «Modify TOMUSS configuration» is in the «Administration» block on column on the right.
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
Assuming you use TOMUSS version 7.0.2 or more recent, you define or redefine an user attribute.
Vectorized database access:
def birth(items):
students = {item.ID_: item for item in items}
request = 'select ID, BIRTH from INFORMATION where ID in {}'.format(students)
for student, birth in database.execute(request):
students[student]['birth'] = birth
configuration.Users.add_attribute(birth)
Sequencial database access:
def birth(items):
request = 'select BIRTH from INFORMATION where ID = %s'
for item in items:
item.birth = next(iter(database.execute(request % item.ID_)))
configuration.Users.add_attribute(birth)
It is possible to define multiple attributes with one request. Look at 'firstname', 'surname', 'mail' attributes in entity.py. It is also possible do define a TTL.
Edit the ACLS table the link «Modify ACLS» is in the «Administration» block on column on the right.
This table define a tree of user groups. You should add the new lines to define more leaves:
| Member | Group |
|---|---|
| your-own-login | roots |
| 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. It is not a good idea to use this trick
The staff groups contains all the users allowed to see the home page and the unprotected table. Never put students in this group.
If needed, users may be removed from an existing group. For example if the LDAP group of teachers contains people that are also student.
TOMUSS currently supports CAS, Unix Passwords, OpenID, FaceBook authentications. The best is to use a CAS (Centralized Authentication Service)
Edit the file LOCAL/config.py.
You will find: configuration.cas = 'https://cas.domain.org/cas'
Set configuration.cas to the URL of your CAS server.
In this case, a web server is required as a frontend to do the authentication.
Edit the file LOCAL/config.py.
You will find: 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]
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 mv DB DB.to_delete mv DBregtest DB ./tomuss.py
TOMUSS send mails to contacts when there is a problem. It also manages students mass mailing. Edit the SMTP configuration in the configuration table. The link «Modify TOMUSS configuration» is in the «Administration» block on column on the right.
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
The maintainer define both the contact mail displayed to the users and the address receiving the alerts when the server has a problem.
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.
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 6 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.
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 = "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.
Two possibles way to display pictures.
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
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
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' ),
)
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.
The 'suivi' servers do modify any data, so it is possible to replicate them on multiple hosts.
Enter some grades into a couple of TOMUSS table.
Start all the 'suivi' servers (and TOMUSS server) in background:
make
See the 'suivi' of a student by one of the following methods:
Other makefile goal are useful : stoptomuss, stopsafe, stopsuivi, restartsuivi,
Once installed, it runs alone. Some administrative actions are displayed to the roots users on the right column on the home page.
Use crontab to schedule some tasks. It is also possible to use TOMUSS planified tasks, they are configurable via a link on the home page. The can launch shell script or any plugin call (as table cell change).
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.
Just to be on the paranoiac side, an hourly backup of the data is a good idea:
rsync --archive --no-g --delete DB/. Distant_Location
SCRIPTS/hour_job can be used to do a backup in a GIT repository.
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:
(cd DB ; git init)
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.
You can create your own installation procedure using SCRIPTS/install as a starting point.
It is really hard to lose data with TOMUSS: