Install ========= verlof package release 0.5.0, Copyright (C) 2002-2005, by Leiden University. verlof is free software. See the file Copying for copying permission. INTRO Verlof is a Web-application to register and view leave (verlof) information. This document describes installation and some administration for the verlof package. The user needs a frame-capable browser with JavaScript 1.3. The verlof server uses the MySQL database management system (dbms) together with the Python scripting language to register and present verlof information. The verlof server can be a host running Unix or Windows NT/2000 server. The installation procedure and tools are for Unix. There is no Windows installation procedure (yet). If you want to install under Windows you can use ./configure, Makefile[.in] and src/script/mkdb.ksh as a guide. Probably cygwin Unix tools for Windows may be of help for installing under Windows. See http://www.cygwin.com. CONTENTS 1. Install required runtime programs 2. Quick installation guide 3. Unpack verlof-0.5.0 distribution 4. Configure verlof package 5. Create verlof database 6. Install verlof package 7. Test installation 8. Caveats A. Administration A.1 HTML Access A.2 Adding HTML access for a host A.3 Adding HTML access for a user A.4 Adding a user entry to the database manually A.5 Changing a user entry in the database manually A.6 Deleting a user entry from the database manually A.7 Deleting a verlof entry from the database manually A.8 Checking the database A.9 Creating a backup from the database B. Supported browsers C. Browser facilities used D. Development D.1 Procedure to update the application release number D.2 Description of files 1. INSTALL REQUIRED RUNTIME PROGRAMS Install the following applications for use at runtime: - a Web-server that supports the use of the Common Gateway Interface (CGI). Alternatively, Python scripts can be executed directly by the Webserver, if the Apache mod_python module is active, see ./configure. The HTML access control in this distribution is based on the use of the Apache Web-server (.htaccess), see http://www.apache.org. - MySQL database management system, see http://www.mysql.com - Python scripting language for CGI programs, see http://www.python.org - MySQLdb Python package to connect to MySQL database, see http://sourceforge.net/projects/mysql-python - mx.Tools Python package, see http://www.egenix.com/files/python/eGenix-mx-Extensions.html#mxBASE NOTE to Solaris users: the Solaris tar program contains a bug that makes building the MySQL and Python packages go astray; instead use GNU tar. See http://www.gnu.org. NOTE to GNU/Linux users: configure is a KornShell script. The 'KornShell' you get via /bin/ksh may actually be zsh. Zsh is not KornShell-compatible enough for configure, so you may need to install the ATT KornShell or the public domain KornShell. More information is available from: http://www.kornshell.com/ and http://www.usinglinux.org/shells/ksh93.html. 2. QUICK INSTALLATION GUIDE $ gunzip -c verlof-0.5.0.tar.gz | tar xvf - $ cd verlof-0.5.0 $ ./configure $ make database # needs MySQL root password # make install # needs host root password 2. UNPACK VERLOF-0.5.0 DISTRIBUTION Unpack the distribution in some directory and cd into it: $ gunzip -c verlof-0.5.0.tar.gz | tar xvf - $ cd verlof-0.5.0 3. CONFIGURE VERLOF PACKAGE Configure the verlof package with the configure script. This creates several files (see below). $ ./configure configure - Configure verlof package Tools: Env: found Python: found Python, compileall: found Application: Release number [0.5.0]: Administrator e-mail address []: Department: Department name [ELD]: Webpage title [ELD verlofregistratie]: Manager e-mail address [Hoofd ELD ]: Web server: Host with HTML [www.eld.LeidenUniv.nl]: Menubar Home URL [http://www.eld.LeidenUniv.nl]: HTML document root [/home/webmgr/public_html/]: Path to HTML [verlof-eld/]: Hosts allowed to view HTML [LeidenUniv.nl 132.229]: Hosts allowed to POST Forms [eld.LeidenUniv.nl 132.229.46]: Use Apache mod_python (y/N) [no]: HTML document owner [webmgr]: HTML document group [webmgr]: Database server: Host with database [localhost]: Database name [ELD-verlof]: Automatically create database accounts (y/N) [no]: Mail server: SMTP host [localhost]: Tools (continued): Creating ./config.status... Creating Readme... Creating Install... Creating Makefile... Creating src/email.txt... Creating src/config.py... Creating src/config.js... Creating src/register.cgi... Creating src/view.cgi... Creating src/.htaccess... Creating src/acl/.htaccess... Creating src/acl/groups... Creating src/acl/passwd... Creating src/script/mkdb.ksh... See also: A.1 HTML Access. ./configure should support the use of a different host for Web serving and for database serving. This has not been tested though. 5. CREATE VERLOF DATABASE Now create the MySQL verlof database and give proper privileges to anyone to see, enter and update records in the database. This requires the MySQL server root password. $ make database Default database access rights are SELECT, INSERT and UPDATE for anyone coming from the Webserver (usually localhost). 6. INSTALL VERLOF PACKAGE Finally install the configured verlof package in the Webserver document tree. # make install The following files are retained if they exist. - {install-dir}/.htaccess - {install-dir}/acl/.htaccess - {install-dir}/acl/passwd - {install-dir}/acl/groups If the Apache webserver mod_python module is not used, files with extension .cgi in {install-dir} must be recognized as and allowed to execute as CGI programs. 7. TEST INSTALLATION Try to enter some verlof entries to the database and check if they show up in the database and arrive as e-mail. 8. CAVEATS Access control is based on the use of the Apache (NCSA) Web server. Webserver specific information not configured: - path: /usr/local/apache: used in src/acl/adduser - access filename: .htaccess A. ADMINISTRATION A.1 HTML ACCESS To be able to enter information into the verlof registratie system, you need the proper access to the Webpages. Access to hosts is granted or denied according to the specifiction in the {install-dir}/.htaccess file. Access to people is granted or denied through accounts as recorded in the {install-dir}/acl/groups and {install-dir}/acl/passwd files. Accounts can be created with the {install-dir}/acl/adduser script. To be able to view the Webpages you need access as specified with the "Hosts allowed to view HTML [eld.fwn.LeidenUniv.nl 132.229.46]:" prompt from ./configure, or you must be able to authenticate yourself via a username and password (account). To be able to enter information you need access as specified with the "Hosts allowed to POST Forms [eld.fwn.LeidenUniv.nl 132.229.46]:" prompt from ./configure, or you must be able to authenticate yourself via a username and password (account). A.2 ADDING HTML ACCESS FOR A HOST Hosts that are allowed to view verlof information are governed by the directive in the {install-dir}/.htaccess file. Hosts that are allowed to register verlof information are governed by the directive in the {install-dir}/.htaccess file. Within the sections you can add subdomain names and network and host addresses to enable hosts to view (or enter) information in the database, for example: Allow from eld.fwn.LeidenUniv.nl 132.229.46 132.229.31.141 A.3 ADDING HTML ACCESS FOR A USER When someone does not have access to the HTML pages or does not have the right to POST a form based on the network or hostaddress, you can provide access via a name, password logon (account). Create a user account with the adduser script in the acl subdirectory of the verlof package installation directory {install-dir}. $ cd acl $ ./adduser {username} New password: Re-type new password: Adding password for user {username} This adds credentials to the passwd and groups files. A.4 ADDING A USER ENTRY TO THE DATABASE MANUALLY There are situations in which the verlof package is not able to determine what to do with a name: match it to an existing one, or enter a new one in the person table. Under this circumstance, the form entry responds with: Your entry has not been added to the database. More than one entry matches your name, probably because: 1. your name is a prefix of someone elses name, OR 2. you did not specify initials with your name, OR 3. you specified your name different from before and I tried to find your name without initials. I behave in this manner to be forgiving in the way you specify your name, allowing small changes over time. However, if your name clashes with someone elses already in the database, you are not able to create an entry for yourself. Unfortunately, this may be the case for you. Adding a user entry manually in short: $ mysql -u root -p mysql> use {database}; mysql> INSERT INTO person (name, email) VALUES ('{name}','{e-mail}'); mysql> exit For example: $ mysql -u root -p Enter password: Welcome to the MySQL monitor. Commands end with ; or \g. Your MySQL connection id is 1270 to server version: 3.23.49-log Type 'help;' or '\h' for help. Type '\c' to clear the buffer. mysql> use ELD-verlof; Database changed mysql> INSERT INTO person (name, email) > VALUES ('Moene-MJ','Martin J. Moene '); mysql> exit A.5 CHANGING A USER ENTRY IN THE DATABASE MANUALLY Changing a user entry from the person table in short: $ mysql -u root -p mysql> use {database}; mysql> -- find name or id: mysql> SELECT * FROM person WHERE name RLIKE '^{name}'; mysql> -- update by id: mysql> UPDATE person SET name={newname} WHERE personID={id}; For example: mysql> SELECT * FROM person WHERE name RLIKE '^moene'; +----------+----------+-----------------------------------------------+-----------+ | personID | name | email | sessionID | +----------+----------+-----------------------------------------------+-----------+ | 9 | Moene-MJ | Martin J. Moene | 0 | +----------+----------+-----------------------------------------------+-----------+ 1 row in set (0.00 sec) mysql> UPDATE person SET name='Moene-MJ' WHERE personID=9; A.6 DELETING A USER ENTRY FROM THE DATABASE MANUALLY Deleting a user entry from the person table in short: $ mysql -u root -p mysql> use {database}; mysql> -- find name or id: mysql> SELECT * FROM person WHERE name RLIKE '^{name}'; mysql> -- delete by id: mysql> DELETE FROM person WHERE personID={id}; For example: mysql> SELECT * FROM person WHERE name RLIKE '^moene'; +----------+----------+-----------------------------------------------+-----------+ | personID | name | email | sessionID | +----------+----------+-----------------------------------------------+-----------+ | 9 | Moene-MJ | Martin J. Moene | 0 | +----------+----------+-----------------------------------------------+-----------+ 1 row in set (0.00 sec) mysql> DELETE FROM person WHERE personID=9; Query OK, 1 row affected (0.00 sec) A.7 DELETING A VERLOF ENTRY FROM THE DATABASE MANUALLY There are many selection criteria to use for deleting one or more verlof entries. Here is just one example: mysql> DELETE FROM verlof, person > WHERE person.name RLIKE '^moene-mj' > AND person.personID=verlof.personID > AND date1='2002-04-26'; A.8 CHECKING THE DATABASE There are many ways to check the database for consistency and validity. You can think of verlof entries for which there is no record in the person table. Here we will collect some of these checks. - persons without verlof entries - verlof entries without matching person entry - unusual hours values - unusual time spans - quesionable e-mail addresses --- to do --- SQL commands A.9 CREATING A BACKUP FROM THE DATABASE MySQL can create update logfiles with SQL commands executed on a database. Keeping the update logs from the very start, you can refill the database with the mysql monitor using these update logs. For this, mysqld must be started with the --log-update option. This is not done at default in the mysql.server startup script. A very simple way to create and use a full backup is shown below. Create a full backup in SQL: $ mysqldump {database} >{database}.full.sql Refill the database with: $ mysql --database={database} < {database}.full.sql B. SUPPORTED BROWSERS - Netscape Navigator 4.5+ - Internet Explorer 4.0+ - Opera 6.02 (JavaScript Amersfoor-ARNO, test: {install-dir}/lib/name.html) - Mozilla 1.0RC1 C. BROWSER FACILITIES USED - frames - forms - JavaScript 1.3 D. Development D.1 Procedure to update the application release number The release number consists of three parts: {major}.{minor}.{trivial} . major the major level number is incremented by one, each time significant changes are made or significant functionality is added minor changes in the minor version number represent added or changed functionality on top of a largely coherent structure; odd minor version numbers are used for development versions, even minor version numbers are used for stable releases trivial the trivial version number usually refers to bug fixes There are several locations where the release number is recorded. Update all relevant numbers when applicable. In the {project} directory: ./ChangeLog (updated by configure) ./Install(this file, updated by configure) ./verlof.lsm (update release number and date manually) Further ./configure requests for the application release number, so it can be used in all ./src/*.in files. D.2 Description of files . - package base directory ./doc - documentation ./src - verlof application ./src/acl - web access control ./src/css - cascading style sheets ./src/img - images ./src/lib - library of html and javascript ./src/script - adduser script .: Readme[.in] - short description of package Install[.in] - description of package, this file Copying - license information News - placeholder FAQ - placeholder ToDo - issues to handle, issues done (includes bugs, see Problems) Problems - description of bugs ChangeLog - release descriptions configure - configure script Makefile.in - Makefile template for ./configure install-sh - BSD install script mkinstalldirs - make directory hierarchy verlof.cpr - ConText editor project file verlof.lsm - package description ./doc: screen.doc - screen shot project.doc - very early project description eld-verlof.doc - latest user documentation (also .pdf) ./src: config.js.dev - configure.js for development config.js.in - config.js template for ./configure config.py.in - config.py template for ./configure email.txt.in - e-mail template file for ./configure help-en.html - package help (EN) help-nl.html - package help (NL) help-admin-en.html - administratve commands (EN) help-admin-nl.html - administratve commands (NL) index.html - toplevel HTML file index.js - toplevel JavaScript menu.html - menubar HTML menu.js - menubar JavaScript null.html - empty HTML file preview.html - register information preview screen register-help-en.html - help on registering (EN) register-help-nl.html - help on registering (NL) register.cgi - register CGI script (runs register.py) register.cgi.unix - register CGI script (runs register.py) register.html - register HTML register.js - register JavaScript register.py - register Python CGI program view.cgi - view CGI script (runs view.py) view.py - view Python CGI program ./src/acl: adduser - create user account groups - groups file groups.dev - groups file for development groups.in - groups file template for ./configure passwd - passwd file passwd.dev - passwd file fot development ./src/css: default.css - general style sheet help.css - style sheet for help screens menu.css - style sheet for menubar register.css - style sheet for register screen view-list.css - style sheet for list view view-total.css - style sheet for total view view-year.css - style sheet for year view view.css - general style sheet for view ./src/img: (snip) ./src/lib: calendar.gif - pop-up calendar picture calendar.html - pop-up calendar HTML calendar.js - pop-up calendar JavaScript (adapted) cookie.js - set and get JavaScript cookie dtio.html - date-time in- and output test page dtio.js - date-time in- and output JavaScript name.html - name handling test page name.js - name handling JavaScript string.js - additions to JavaScript built-in String class ./src/script: mkdb.bat - batch program to drive mkdb.ksh mkdb.ksh - Korn-shell script to create MySQL database with tables person and verlof mktbl.sql - SQL used by mkdb.ksh (creates person and verlof tables) $Id: Install.in 18 2005-09-06 11:15:33Z moene $ *** End of INSTALL ***