This file explains the peculiarities of the Debian package for Wims.

1. INTRODUCTION: WHAT THIS PACKAGE IS FOR
=========================================

The main goal of the package Wims in Debian is to make easier the
installation of the web-service Wims for administrators.

Installing Wims from sources distributed at http://sourcesup.cru.fr/
is *not* straightforward, you must get a handful of dependences, and
create a compilation environment, which is not wanted on a web-server.

Installing the binary packages from Debian makes this much easier:
just "apt-get install wims", drink a cup of coffee, et voilà!.

Wims is a powerful web-service, which can provide homeworks for all of
the students of a university, quite out of the box. The Debian package
aims to help admins to install Wims. However it does not cover every
detail of the daily administration of such a web-service.

2. TASKS TO PERFORM WHEN THE PACKAGE HAS JUST BEEN INSTALLED
============================================================

2.1. MAKE A TOUR
================

With common settings, as the package wims recommends the package
wims-extra-all, you immediately get a web-service with interesting
features, and you can begin playing with it at the URL
http://localhost/wims

The web-service is generally available as http://<servername>/wims .
Initially, only accessing it through http://localhost/wims allows one
to enter the administration facility. Accessing it in other ways will
not display that entry.

2.2. CREATE AN ALIAS TO GET E-MAILS
===================================

People who want to send an e-mail to the administrator are hinted to send 
it to the wims user. So it may be necessary to define some alias in 
/etc/aliases to redirect such email to the wims administrator mailbox.


2.3. ENTER THE ADMINISTRATION FACILITY
======================================

When you access the URL http://localhost/wims, you are provided a link
to an administration facility. Follow that link, and you will be
prompted to read a secret in a dynamically generated file which is
only readable by the system user wims (if you provide it a usable
shell) or the user root. So if you are privileged enough to read it
either as wims or as root, you can access the administration pages for
Wims.

For example, you can do the following:

$ sudo cat /var/lib/wims/tmp/log/.wimspassone

and then copy the password into the application form to enter the
administration facility

2.4. UPGRADE THE MODULES AND INSTALL NEW ONES
=============================================

The package wims-extra-all provides a rich set of modules which were
made for the version 3.62 of Wims. Those are still fully working with
the latest version of Wims. However many of them have been superseded
by updates, and the latest version of Wims considers as "standard" a
set of packages which did not ever exist in wims 3.62, for example:
the FAQ module (frequently asked questions about Wims, which should be
available through a web link in the main page of the service).

To get the latest sets of packages, enter the administration facility,
then go to the modules administration pages. After some analysis, a
list of installable packages will appear, and you are prompted a few
questions, in order to select sets of packages to install. The
packages are maintained outside the Debian archive. If you want get
some feedback, or report a bug about them, subscribe to
http://www.wimsedu.info

2.5. INSTALL OPTIONAL SUGGESTED SOFTWARE
========================================

Wims recommends the free programs yacas, gap, and the package
wims-help. It suggests wims-extra-all.

Yacas is a computer algebra system, like Maxima, with different
features. Some modules authored by math teachers depend on Yacas.

Gap is another computer algebra system, for computational discrete
algebra with particular emphasis on computational group theory.  Some
modules authored by math teachers depend on Gap.

Wims-help provides web pages like wimsFAQ, examples of short programs in 
OEF language, and much more.

Wims-modules provides a very minimal subset of modules. Wims-extra-all
adds most teaching modules which existed in year 2009, which make the
web-service more enjoyable. If you installed just wims and wims-modules,
the internal search engine does not find anything, as there is still no
educational module.

2.6. INSTALL OPTIONAL SUGGESTED NON-FREE SOFTWARE
=================================================

Wims suggest a few non-free programs like Povray. For example, Povray:
if you install povray, you will have to run again the
post-installation of wims : 'dpkg-reconfigure wims', in order to have
the setup working.

3. ORDINARY HOUSEKEEPING FOR WIMS 
=================================

Here are examples of tasks which are performed periodically by
administrators of Wims web-services:

3.1. CREATE DEVELOPMENT ACCOUNTS 
================================

You can grant users who ask about it, the right to enter the
development area. Enter the administration facility and go to the
development accounts management pages. When a user can develop modules
on your website, she can edit educational modules with various tools,
and store them locally in a so-called development area. Modules
created by users can drain a part of the server's computing power;
however each module is given a limited time to run and a limited
memory size, so no user can damage the web-service by a badly shaped
module.

A user who created a module in the development area can include them
in her own virtual classes. She can also publish them, but must
receive an accreditation previously by managers of
http://www.wimsedu.info

To publish a module world-wide, it must bear a free license and be
reviewed and approved by a member of the association WimsEdu in charge
of some domain of modules.

3.2. RE-INDEX MODULES
====================

After the installation of new modules, some indexes need a
rebuild. This can be scheduled with the administration facility

3.3. MANAGE BACKUPS
===================

Wims is not so particular that it would need a specialized backup
procedure.  Quite everything can be restored by installing again the
package and updating the public modules.

The reminder should be secured using general purpose backup
applications.

The only peculiarity is about virtual classes: each of them has an
expiration date. When this date has come, all of the files for this
virtual class are put into a tarball, the access to the class is
closed, and an e-mail is sent to the owner of the class. This e-mail
gives the name of the tarball which contains the internals of the
virtual class. If the owner sends you a copy of this e-mail, you can
easily find that archive of the class and send him a copy of this file.

3.4. MANY OTHER THINGS
======================

- Configure appearances, virtual classes, documents, forums, resource
  restrictions, etc.
- Check the system
- Check and maintain virtual classes, documents, current server
  activities, etc.
- upload resources to the server, etc.

4. DON'T DOs
============

Do not upgrade the server by using the administration facility. If you
do so, Debian's tool management system will not be aware of 
changes introduced by you, and it will disturb them during some update 
in the future.

If you really want to quit Debian's management system to rely only on
the system provided by the authors of Wims, then you should consider
version pinning of the current version of Wims, wims-modules and 
eventually wims-extra-all. To perform version pinning, see for example:
http://www.linuxtopia.org/online_books/linux_system_administration/managing_debian_software_with_apt/ch-apt-get.en_009.html

 -- Georges Khaznadar <georgesk@ofset.org>, Mon,  9 May 2011 18:55:18 +0200
