Installation of QuizComposer (Open source/GPL)

Installation of QuizComposer on current UNIX/Linux Web-server.

This is an HTML-page (install.htm) in the QuizComposer software system. Together with a companion CGI-program (install.py) it can be used to install the QuizComposer system on a computer with the UNIX or Linux operating system, the Apache Web server program (or other server program, presumably), the Bash shell and the Python programming language.

You are expected to have a little experience with UNIX/Linux, Bash and Apache configuration.

You must be either the administrator (root) of the computer or be a user having appropriate rights to install a Web server, either somewhere on the computer or in your home directory. For example, you could be the "User" of the Apache server as defined in the configuration file for the server. You might find this configuration file in a directory under /etc/httpd/conf. You might also be one among a number of users of a computer system haviing an account permitting you to set up a Web server the first page of which has a Universal Resource Location with a format like www.abc.xy/~user. Or you might be the administrator (root) of such a system wishing to set up such a user. In any case, you must have access to two directories, one for Web pages and one for CGI-scripts. In the configuration file they might be defined by the so-called directives DocumentRoot and ScriptAlias. Common names for the directories are public_html and cgi-bin, respectively.

Furthermore you must have access to a "home" directory into which a directory (normally with the name quizcomposer) with the QuizComposer programs and data files will be placed together with directories containing quizzes and questionnaires created by the authors. The "home" directory will also contain a directory (quizcomposerinstall.d) in which all install files (except install.htm and install.py) will be placed. In what follows this directory is denoted the install directory.

Installation of the QuizComposer system commences with the copying of this HTML-page (install.htm) to the DocumentRoot and the companion CGI-program (install.py) to the ScriptAlias and setting appropriate access rights for these files.

You might have to make one or more alterations to the copy of this file, which you put in DocumentRoot. This can be checked as follows. Point to the HTML page with your browser, LEAVE THE PASSWORD FIELD EMPTY, and click any button. IF YOU DO *NOT* GET A MESSAGE ABOUT A MISSING PASSWORD, YOU PROBABLY HAVE TO CHANGE THE ACTION PARAMETER IN THE FORM TAG (the line containing '<FORM ...>'). The first part of the parameter, i.e. /cgi-bin/ must be changed to the first element in the ScriptAlias directive. Other posibilities are that the path to the install program (install.py) does not correspond to the last element in the ScriptAlias directive or that the access rights to one of the two files have not been set correctly.

If, in the test above, YOU DO GET A MESSAGE ABOUT A MISSING PASSWORD, you should go on to consider the values of the install variables in the large entry field. The contents of this field is a shell script used (via the source command) as part of the install script performing the installation. All lines starting with a hash (#) are comments. All other lines define the value of an install variable. Some comment lines display an example value for an install variable. You may wish to alter the value of one or more of these variables so that you won't have to enter the values every time you perform the installation. Values containing a $-sign are evaluated during installation according to the environment for the installation. You can get a listing of the environment by clicking the appropriate button further down in the form. You can also get an evaluation of the values which depend on the environment by clicking an appropriate button further down.

It might be a good idea to copy the complete entry field into a local file for editing and to save the file for subsequent re-installations.

One install variable which can be tricky to set is the CGINAME. If you leave it unset the install.py program will determine the value by scanning the install.htm page for the ACTION parameter in the FORM tag and use that prefix to install.py. In some cases this may not be correct (due partly to the way the Web server is configured, partly to the way Web pages in QuizComposer are placed). You may try to set CGINAME to ../cgi-bin/ or cgi-bin/. Ask for help if you are stuck.

The complete text of the entry field for setting install variables will be copied by the install.py program to a file install.var in a sub-directory of the install directory used for the installation process. The name given to that sub-directory is the date of the installation process (re-installations on the same day use the same sub-directory). Notice the difference between the install directory and the install sub-directories.

Before clicking the the button marked INSTALL QUIZCOMPOSER make sure you are connected to the Web from where two files will be fetched, namely the install script install.sh, and the file install.tgz containing the QuizComposer system itself. Both are read from www.quizcomposer.dk and placed in the installation sub-directory mentioned above. Execution of the install script (install.sh) accomplishes the installation process. Apart from the installing QuizComposer onto your Web server the installation process creates two files, install.log and install.err into the sub-directory for installation. You can have these files displayed by clicking appropriate buttons in the install.htm page. Furthermore, if your QuizComposer installation is to use external programs (such as YACAS) for checking answers to quiz questions, prior to starting the installation process you must place appropriate interface programs (between QuizComposer and the external programs) into the install directory. Using external programs is indicated in an install variable XCHK, see below in the field for defining install variables. The install script install.sh copies the interface programs into the ScriptAlias directory (among the other excutables). Interface programs are sometimes also denoted checker programs.

After an installation you can go to the installation sub-directory (and any previous "neighbouring" sub-directory) and re-perform the installation with the command:
bash install.sh > install.log 2> install.err
or similar. You might wish to alter some of the values for the install variables (by editing the file install.var) or any interface program before excuting the command. Notice that the bash command above is executed in an environment different form the one executed by install.py. Thus, no installation variable may depend on the the latter environment. The environment for the directly executed bash command can be listed with the command env.

Alternatively, you can carry out a re-installation via the install.htm page by pressing the install button after having copied the currently defined install variables (possibly modified) into the entry field for these values. If this is the first installation for the current date (today) a new sub-directory for installation is created - unless you have already created such a directory. Unless the sub-directory already contains files install.tgz and install.sh, these are copied in from www.quizcomposer.dk. If you wish to perform the install process with your own version of the install.sh script under the original environment create the sub-directory with that script in it. (The file install.var is ALWAYS read from the entry field for install variables in the install.htm page even if a file with that name already exists in the sub-directory).

It is IMPORTANT TO NOTICE, that the first non-empty password you type in the first entry field of the installation form (install.htm) will be crypted and the crypt value inserted into the install.py program. On subsequent re-installations you must state the same password. If you forget the password you must remove the crypted password (between quotes) in install.py prior to a new installation.

You can find more information about the install process in the install.py file.

Configuration variables:

# This is a sample shell script (install.var) in the suite of software
#  for installation of the QuizComposer(c) system.
# This script is executed from the main installation script (install.sh
#  or install.sh.txt).
# This script defines the variables for the installation process.
# You are expected to edit a copy of this script by entering
#  appropriate values for the variables for the Web-server on
#  which you want to install QuizComposer(c).
#
# Some of the values to be chosen depend on the configuration of the
#  Web server.
# If you have acces to the Web servers configuration file look for
#  the values there.
# Otherwise consult your Web servers guide to installing home pages
#  and CGI scripts.
#
# Please look into the file guide_en.txt for more information.
# QuizComposer(c) system (Open source/GNU Affero General Public License).

# The domain name of the Web server (explanation below):
export DOMAIN=$(s=${HTTP_REFERER:7} ; echo ${s/\/install.htm/})
#export DOMAIN=$(s=${HTTP_REFERER:7} ; echo ${s/\/install.htm/})
# This is what the users write following http:// to access the server
#  on which the quiz server is installed, for example: www.someplace.sw.
# NOTICE: HTTP_REFERER is defined only when installation is a CGI process

# The directory in which QuizComposer is to be installed:
export QUIZCOMPOSERPARENT=
#export QUIZCOMPOSERPARENT=
# Here QuizComposer represents the directory which during installation
#  contains the software constituting QuizComposer.
# The same directory will during use contain the collections of quizzes
#  created by the authors or at least links to such collections.
# A trailing / is NOT permitted.

# The name of the directory for QuizComposer as defined above:
export QUIZCOMPOSERNAME=quizcomposer
#export QUIZCOMPOSERNAME=quizcomposer
# Choose another name if you like, for example in case of a reinstallion.

# The 'DocumentRoot' directory where HTML-pages are normally stored:
export HTMLDIR=$DOCUMENT_ROOT
#export HTMLDIR=$DOCUMENT_ROOT
# Common values are /home/httpd/html or /var/httpd/htdocs.
# Look into the documentation for the Web server.
# For example for Apache look into /etc/httpd/conf/commonhttpd.conf
#  or similar.
# A trailing / is NOT permitted.
# NOTICE: DOCUMENT_ROOT is defined only when installation is a CGI process

# The directory for CGI scripts:
export CGIBINDIR=${SCRIPT_FILENAME//\/install.py/}
#export CGIBINDIR=${SCRIPT_FILENAME//\/install.py/}
# Common values are /home/httpd/cgi-bin or /var/httpd/cgi.
# Look into the documentation for the Web server.
# For example for Apache look into /etc/httpd/conf/commonhttpd.conf
#  or similar.
# A trailing / is NOT permitted.
# NOTICE: SCRIPT_FILENAME is defined only when installation is a CGI process

# The 'ScriptAlias' to be used in FORM-element of HTML-pages with forms:
export CGINAME=
#export CGINAME=
#export CGINAME=$(IFS=/; ar=($SCRIPT_NAME); n=${#ar[*]}; echo ${ar[n-2]})
# Containing the last part of the value of CGIBINDIR (defined above)
#  with a trailing slash, for example /cgi/ or /cgi-bin/ or ../cgi-bin/.
# Look into the documentation for the Web server.
# NOTICE: SCRIPT_NAME is defined only when installation is a CGI process
# NOTICE2: when you set CGINAME to an empty value (as above)
#   the install program install.py will set its value according to the
#   ACTION parameter in the FORM tag in the install.htm file.
#   If this should fail, you must set CGINAME manually as the value of
#    ScriptAlias as stated in the configuration file for the server.

# Set the following variable to 1 or yes if you wish to save the current
#  installation with user quizzes and all prior to a re-installation:
export SAVE_CURRENT=
# export SAVE_CURRENT=
#  Saving is done once only in a sub-directory for installation (only
#  one sub-directory for installation is created per day).

# The following variable is only set for a "virgin" Web site, i.e. when
#  the Web site is created.
# Changing the value after the Web site is created can be very complex.
# The real or modified e-mail-address for the QuizComposer administrator.
export ADMINMAILADDRESS=abc@@def.xy.
#export ADMINMAILADDRESS=abc@@def.xy.
# The value is also the name of the public directory for the QuizComposer
#  administrator.
# It is said to be a modified e-mail address if it contains a @@ in place
#  of the normal @ in an e-mail address and/or if it ends with a dot (.).
# Normally you should use the modified format for the reasons below.
# The administrator will recieve mail at the e-mail addresss derived from
#  the modified address. 
# The @@ implies that quizzes created by admin, if any, will not contain
#  an entry field for comments from answerers.
# The trailing dot implies that admin will not be included in any list of
#  quiz authors presented to quiz answerers.

# The following variable is only set for a "virgin" Web site, i.e. when
#  the Web site is created.
# The value can be changed later as for any other password.
# The 8-12 character password for the QuizComposer administrator:
export ADMINPASSWORD=46-34=12
#export ADMINPASSWORD=46-34=12
# Do NOT use the administrators password to the computer system.
# The value of ADMINPASSWORD is to be used in the special form for
#  administration (creation, deletion and other operations) of
#  quiz authors.

# The following variable is only set for a "virgin" Web site, i.e. when
#  the Web site is created.
# Changing the value after the Web site is created can be very complex.
# The real or modified e-mail-address for the special quiz author having the
#  name test:
export TESTMAILADDRESS=test@@.
#export TESTMAILADDRESS=test@@.
# The value of TESTMAILADDRESS is also the name of the public directory
#  for that author.
# Concerning the modified format see comments above on the e-mail-address
#  of the QuizComposer administrator.
# The two directories for this special author (test) are used for trial
#  quizzes and questionnaires.
# The quiz server administrator can use the identity test for testing
#  purposes.

# Depending on the server configuration it seems that the installers
#  group may have to be given owner rights.
# In this case set GROUPPERM to a non-empty value, e.g. 1:
# export GROUPPERM=
# For details look into the install script: install.sh or install.sh.txt.

# If installer name (e.g. apache) is not the name of the user under which
#  the server runs state the user name and group of the latter:
#  export SERVERUSER=nobody ; export SERVERGROUP=nogroup
# Look into the configuration file for the Web server, e.g. for Apache:
#  /etc/httpd/conf/commonhttpd.conf (or similar).

# Group name for directory HTMLDIR and its contents if different from
#  value of SERVERGROUP:
#  export HTMLGROUP=*********
# Look into the configuration file for the Web server.

# Group name for directory CGIBINDIR and its contents if different from
#  SERVERGROUP:
#  export CGIBINGROUP=*********
# Look into the configuration file for the Web server.

# List of socalled external checkers, i.e. Python progams to be imported
#  and executed by the answer checking program (mod_chkanswer.py).
# List must be comma-separated and have no space characters.
# Example: export XCHK=maple,algebra
# Install directory must contain the programs, here: maple.py and algebra.py.
#  These are copied to the directory CGIBINDIR defined above. Notice that
#  the names in the XCHK list do not .py.
# Checker programs must define a function check with an argument list as
#  shown in the install script install.sh or install.sh.txt (search for
# calllist). The arguments are
#  1: the specification of the correct answers
#  2: the answer
#  3: a function for writing any message to the answerer prior to exiting;
#     the function takes a single argument: the message
#  4: the language of the quiz (dk: danish, en: english)
#  5: the number of the current question
#  6: the full specification of a correct answer for the question (possibly
#     useful for debugging)
# Notice: the use of any proprietary software in a checker program is the
#  responsility of you the installer, only.
# export XCHK=yacas

# The intall program creates a temporary directory  $QUIZCOMPOSER/tmp
#  where $QUIZCOMPOSER=$QUIZCOMPOSERPARENT/$QUIZCOMPOSERNAME.
#  To be used by all external programs during install and server execution.

# The install program executes any scripts indicated in the variable XSCRIPTS
#  defined by:
#   export XSCRIPTS=s
#  where s is a comma separated list of names of scripts placed in the
#  install directory (i.e. the location of the install program).
# Each script is executed as if it is part of the install program, e.g.:
#   . x.sh
#  where x.sh is the name of a script.

# You may set the location of the Python interpreter on the server:
export PYTHON=
# If empty, PYTHON will be set according to the first line of install.py.
# Other possibly useful forms:
# export PYTHON=$(which python)
# export PYTHON=/usr/bin/python
# export PYTHON='/usr/bin/env python'

# If you wish to allow guest accounts remove The # in:
# export GUEST_MAXCOUNT=10
#  and change the number if you wish.
# Any person can then reserve an account as a private (autonomous) author
#  as long as the maximal count of accounts does not exceed GUEST_MAXCOUNT.
# The account names will get the name d*QC where d* signifies a sequence
#  of digits. The length of the sequence d* is one more than the length
#  of the digits in GUEST_MAXCOUNT.
# A guest account can hold only a limited number of quizzes and/or
#  questionnaires, no files can be downloaded to a guest account and
#  it cannot recieve mail.
# *REMEMBER* to uncomment the statement above before reinstallation.
# You must also set the number of hours a guest account should be open
#  to a holder by removing # on the next line and altering the number:
# export GUEST_HOURSOPEN=72
# Normally two guest accounts can not be reserved from the same remote
#  IP address. This is not checked if GUEST_IPNOCHK is set:
# export GUEST_IPNOCHK=1
# Any problems with the guest accounts will be mailed to the mail address
#  of the server administrator specified above.

# Installation of system with removal of source files:
export LEVEL=min
#export LEVEL=min
# If LEVEL is set to min or empty (LEVEL=) the directory with files
#  for creating an installation file containing all source code is removed.
# If LEVEL is set to max install.tgz will be copied to rqstinst.d
#  which will then contain the complete set of installation files
#  for anybody to copy.

# Some servers seem to require ../ as prefix to html.d in html.d/index.html (the
#  QuizComposer home page). If so, change the following statement into
#  export INDEX_HTML_PREFIX1=../
#  (or whatever prefix is required)
export INDEX_HTML_PREFIX1=
#export INDEX_HTML_PREFIX1=
 
# If you want to have the sourceforge logo displayed on html.d/index.html (the
#  QuizComposerhome page) change the following statement into
#  export SOURCEFORGE_LOGO=1
export SOURCEFORGE_LOGO=
#export SOURCEFORGE_LOGO=

# If you want a .htaccess file containing 'Options -Indexes' created in 
#  the public directory of a course set:
#   export HTACCESS=1
# If you want a .htaccess file containing something else set:
#   export HTACCESS='something'
# If you don't want any .htaccess file in the public directory of a course set:
#   export HTACCESS=''
# The latter seems important on SUN servers in order to have image files
#  and the ilk displayed.

# Normally only at www.quizcomposer.dk:
# export QUIZCENTER=yes
# export INSTALLINSTALLFILES=yes

Password:

List environment variables for server:

List above install configuration with variables evaluated:

Install QuizComposer system according to above configuration:

List error log file (install.err) for last installation

List log file (install.log) for last installation

Show list of files and directories in install directory:

Delete directories under install directory:
Date (= name) of first directory to delete:
Date of last directory to remove: