This installation instruction assumes that KIX is installed in a UNIX style web server environment such as apache under linux. However, the installation can be adapted to any web server environment that support perl CGI scripts.
The CGI scripts need to be able to write to files. At least one file - the KIX database lock file - needs to be local to the server. This is a linux/Solaris requirement. All other files may be accessed via a networked file system.
KIX workflow notifications to other KIX users depend on the ability to send e-mail. Furthermore, if one or more KIX federation is needed, the federate KIX servers need bi-directional communication with each other via HTTP.
KIX summary notifications by e-mail require regular execution of a script. In a UNIX style environment regular execution is normally achieved by cron jobs. Thus the present version of KIX depend on the ability to use cron jobs.
Advanced federation features (such as automatic actions as a result of changes to dependency documents held in a federate KIX server) also depend on the execution of cron jobs.
KIX Installation Overview
The following executable application components will be needed to support a fully functional installation of KIX:
- cgi-scripts
- scripts common to all KIX instances in use on the same server
- scripts specific to each instance of KIX
- command line scripts
- script common to all KIX instances in use on the server account
- 3util - low level KIX database maintenance script
- script specific to each instance of KIX
- init_kixfw - script to initialise the KIX database
- cron job scripts
- script specific to each instance of KIX
- kix-regular - cron job script (if KIX summary notifications via e-mails are required)
Plan the KIX Installation
Before the installation can begin a number decisions has to be taken. The installation must establish a number of file system directories where the files, which supports the KIX installation are held. The following directories are needed:
- DEPOT where downloaded files are kept,
- lib where perl modules are kept or linked,
- bin where generic command line tools are kept,
- templates where HTML template files for the PythonTech templater are kept or linked,
- etc where the htpasswd authentication userid file is kept,
- sessions where the login session database is kept,
- data where the KIX databases and directly related command line scripts are kept, as well as KIX document content files (option from version 1.12),
- cgi where CGI scripts are kept and
- x3plogs for optional debugging of X3P communication in KIX federations.
Install Perl Download Modules
It is recommended that the latest versions of the following perl modules are downloaded, uncompressed and untared:
- Download from MetaAgility
- KixFw
- X3P
- MetaAgility-Reason
- MetaAgility-DataBox
- Download from PythonTech
- PythonTech-Cfw
- PythonTech-Conv
- PythonTech-Model
- PythonTech-QMap
- PythonTech-Template
- PythonTech-Triples
- PythonTech-WebServer
- Optionally download the following KIX plugins from MetaAgility
- KixPlugin-DocReview
- KixPlugin-Export2File
- KixPlugin-KixPlugin-Wiki2Html
- Optionally download (from for example CPAN )
- CGI::Session
A Flexible KIX Directory Structure for Downloads
In particular if you plan to take part in the development and upgrade of KIX it is important to arrange the downloaded components in such a way that new versions can be easily installed and removed. This is easy if the scripts access the different current versions via symbolic links.
See here for advice on how to arrange a flexible KIX directory structure for installation of downloads.
Install HTML Templates for the PythonTech Template Module
The KixFw framework and several of its plugin depend on many HTML templates, which are processed by the PythonTech Template module.
The templates may for future convenience be linked to the downloaded modules in the same way as the perl sources. See the installation instructions for the templates directory.
Create the 3util Script
The 3util command line script is a simple RDF triple database utility. It is not yet distributed by PythonTech, but 3util can easily be created from these instructions.
The 3util command line utility is of real assistance when investigating and resolving low level database problems with the KIX databases (they are all RDF triple databases).
Configure KIX - Install cfw_kix.pm
KIX depend on the CFW module from PythonTech for its main configuration. In order to configure KIX the cfw_kix.pm file must be installed and adapted to the local KIX server environment.
See cfw_kix.pm for installation and configuration details.
Install the init_kixfw Script and Create the KIX Database
Once KIX has been configured and the KIX data directory has been created it is time to install the init_kixfw utility script in that directory.
This script can then be used to initialise the KIX database as configured by cfw_kix.pm.
Install and Configure the CGI Local.pm Module
Most CGI perl scripts distributed with kixfw use the configuration Local.pm perl module. This module need to be installed and configured before any of the dependent perl scripts can be used.
See the installation instructions for the Local.pm perl module.
Install and Test the KIX Framework CGI Script - kixfw
With all the above preparations completed it should now be trivial to install and test the main kixfw script. See the installation instructions for the kixfw perl CGI script.
To test the KIX installation simply type the configured KIX URL in your favourite browser and you should be invited to a KIX login. However, login is not supported, until the login CGI script has been installed (see below).
Trouble Shooting KIX and Other CGI scripts
When working with and developing CGI scripts it is often difficult to understand why scripts sometimes don't work. This is particularly so if you have no access to the error log of the HTTP server (which is often the case when a hosted HTTP service is used).
It is then useful to wrap the CGI perl script using a simple wrapper shell script, which catches the errors and presents them in your browser window.
Here are instructions on how to install such a wrapper shell script.
Creating a Password File in the etc Directory
Before you can login to KIX you need to establish the KIX authentication. If you intend to use KIX as it was distributed by MetaAgility it is assumed that every KIX userid is accompanied by a pair of userid and encrypted password in a users file in the etc directory.
There are many ways to establish such a file. Here are instructions on how to do it using the htpasswd utility (htpasswd is part of the apache distribution).
Installing the login and logout CGI Scripts
Here are instructions on how to install the login CGI script.
And here are instructions on how to install the logout CGI script.
The login and logout CGI scripts are the last items required to fully operate KIX as a web user.
After the first login to KIX it should be possible to see the user account which was created by the init_kixfw script when the KIX database was created (see above). This account is to be found in the users folder, which is the only subfolder to be found in the otherwise empty top level KIX folder.
Installing the kix-regular Script and Configure cron jobs
Here are instructions on how to install the kix-regular cron job script.
This script is used by KIX to send regular e-mails with summaries of KIX user notifications. The script also performs deferred plugin actions as a result of events received from remote dependency documents in any configured KIX federation server.
Installing the kixshow CGI Script
Here are instructions on how to install the kixshow CGI script, which may be used by KIX admin users to view and patch the low level content of the KIX database.
Installing the x3pkix CGI Server Script
Here are instructions on how to install the x3pkix CGI script.
This script provides the KIX intallation with an X3P server, which is used for KIX federation access. Since KIX federations rely on the X3P peer-to-peer protocol such federations cannot operate at all unless the x3pkix script is configured.
On the other hand if the KIX installation does not configure any federate KIX servers the x3pkix script is not needed at all.
That's it - Enjoy Working with KIX
KIX is a simple but serious tool for distributed engineering. KIX real power only comes to light when it is extended by plugins which targets the document types of one's working domain and integrates KIX with one's working processes.
There are a few generic KIX plugin's, which are distributed by MetaAgility as open source:
- KixPlugin-Wiki2Html - transforms parts of a KIX repository to a distributed web content management system,
- KixPlugin-Export2File - simple integration tool which export KIX documents as external files,
- KixPlugin-DocReview - provides support for high precision distributed document reviews.
See KIX plugins for starter instructions on how to extend KIX with these and other plugins.