wkix: /
content /
8
001: '''KixFw 1.12 Installation Prerequisites'''
002:
003: 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.
004:
005: 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.
006:
007: KIX workflow notifications to other KIX users
008: depend on the ability to '''send e-mail'''.
009: Furthermore, if one or more KIX federation
010: is needed, the federate KIX servers need '''bi-directional'''
011: communication with each other via '''HTTP'''.
012:
013: 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.
014:
015: 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.
016:
017: |
018:
019: '''KIX Installation Overview'''
020:
021: The following executable application components will be needed to support a fully functional installation of '''KIX''':
022:
023: * '''cgi-scripts'''
024: ** scripts common to all KIX instances in use on the same server
025: *** ''[[installation/dirs/cgi/login/content/][login]]'' script
026: *** ''[[installation/dirs/cgi/logout/content/][logout]]'' script
027: ** scripts specific to each instance of KIX
028: *** ''[[installation/dirs/cgi/kixfw/content/][kixfw]]'' - KIX framework script
029: *** ''[[installation/dirs/cgi/x3pkix/content/][x3pkix]]'' - KIX federation server script (if X3P support for KIX federations is required)
030: *** ''[[installation/dirs/cgi/kixshow/content/][kixshow]]'' - KIX database viewing and patching script
031: * '''command line scripts'''
032: ** script common to all KIX instances in use on the server account
033: *** ''[[installation/scripts/3util/content/][3util]]'' - low level KIX database maintenance script
034: ** script specific to each instance of KIX
035: *** ''[[installation/scripts/init_kixfw/content/][init_kixfw]]'' - script to initialise the KIX database
036: * '''cron job scripts'''
037: ** script specific to each instance of KIX
038: *** ''[[installation/dirs/etc/cron/content/][kix-regular]]'' - cron job script (if KIX summary notifications via e-mails are required)
039:
040: |
041:
042: '''Plan the KIX Installation'''
043:
044: 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:
045: * '''[[installation/dir_advice/content/][DEPOT]]''' where downloaded files are kept,
046: * '''[[installation/dirs/lib/content/][lib]]''' where perl modules are kept or linked,
047: * '''[[installation/dirs/bin/content/][bin]]''' where generic command line tools are kept,
048: * '''[[installation/dirs/templates/content/][templates]]''' where HTML template files for the PythonTech templater are kept or linked,
049: * '''[[installation/dirs/etc/content/][etc]]''' where the ''htpasswd'' authentication userid file is kept,
050: * '''[[installation/dirs/sessions/content/][sessions]]''' where the login session database is kept,
051: * '''[[installation/dirs/data/content/][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),
052: * '''[[installation/dirs/cgi/content/][cgi]]''' where CGI scripts are kept and
053: * '''[[installation/dirs/x3plogs/content/][x3plogs]]''' for optional debugging of X3P communication in KIX federations.
054:
055: |
056:
057: '''Install Perl Download Modules'''
058:
059: It is recommended that the latest versions of the following perl modules are downloaded, uncompressed and untared:
060:
061: * Download from [[http://www.metaagility.com/sw_distribution/][MetaAgility]]
062: ** ''KixFw''
063: ** ''X3P''
064: ** ''MetaAgility-Reason''
065: ** ''MetaAgility-DataBox''
066: * Download from [[http://www.pythontech.co.uk/perl/][PythonTech]]
067: ** ''PythonTech-Cfw''
068: ** ''PythonTech-Conv''
069: ** ''PythonTech-Model''
070: ** ''PythonTech-QMap''
071: ** ''PythonTech-Template''
072: ** ''PythonTech-Triples''
073: ** ''PythonTech-WebServer''
074: * Optionally download the following KIX plugins from [[http://www.metaagility.com/sw_distribution/][MetaAgility]]
075: ** ''KixPlugin-DocReview''
076: ** ''KixPlugin-Export2File''
077: ** ''KixPlugin-KixPlugin-Wiki2Html''
078: * Optionally download (from for example [[http://search.cpan.org/dist/CGI-Session/][CPAN]] )
079: ** ''CGI::Session''
080:
081: |
082:
083: '''A Flexible KIX Directory Structure for Downloads'''
084:
085: 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.
086:
087: See here for advice on how to arrange a
088: '''[[installation/dir_advice/content/][flexible KIX directory structure]]''' for installation of downloads.
089:
090: |
091:
092: '''Install HTML Templates for the PythonTech Template Module'''
093:
094: The '''KixFw''' framework and several of its plugin depend on many
095: HTML templates, which are processed by the PythonTech Template module.
096:
097: The '''[[installation/dirs/templates/content/][templates]]''' may for future convenience be linked to the downloaded modules in the same way as the perl
098: sources. See the installation instructions for the
099: '''[[installation/dirs/templates/content/][templates]]''' directory.
100:
101: |
102:
103: '''Create the 3util Script'''
104:
105: The '''3util''' command line script is a simple RDF triple database utility.
106: It is not yet distributed by PythonTech, but '''[[installation/scripts/3util/content/][3util]]'''
107: can easily be created from
108: '''[[installation/scripts/3util/content/][these instructions]]'''.
109:
110: 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).
111:
112: |
113:
114: '''Configure KIX - Install cfw_kix.pm'''
115:
116: KIX depend on the CFW module from PythonTech for its main configuration. In order to configure KIX the
117: '''[[installation/dirs/lib/cfw_kix/content/][cfw_kix.pm]]''' file must
118: be installed and adapted to the local KIX server environment.
119:
120: See
121: '''[[installation/dirs/lib/cfw_kix/content/][cfw_kix.pm]]'''
122: for installation and configuration details.
123:
124: |
125:
126: '''Install the init_kixfw Script and Create the KIX Database'''
127:
128: Once KIX has been configured and the KIX
129: '''[[installation/dirs/data/content/][data]]''' directory has been
130: created it is time to install the '''[[installation/scripts/init_kixfw/content/][init_kixfw]]'''
131: utility script in that directory.
132:
133: This script can then be used to initialise the KIX database
134: as configured by '''cfw_kix.pm'''.
135:
136: |
137:
138: '''Install and Configure the CGI Local.pm Module'''
139:
140: Most CGI perl scripts distributed with '''kixfw''' use the configuration
141: '''[[installation/dirs/cgi/local/content/][Local.pm]]''' perl module.
142: This module need to be installed and configured before any of the dependent
143: perl scripts can be used.
144:
145: See the installation instructions for the
146: '''[[installation/dirs/cgi/local/content/][Local.pm]]''' perl module.
147:
148: |
149:
150: '''Install and Test the KIX Framework CGI Script - kixfw'''
151:
152: With all the above preparations completed it should now be trivial to install and test the main
153: '''[[installation/dirs/cgi/kixfw/content/][kixfw]]''' script.
154: See the installation instructions for the
155: '''[[installation/dirs/cgi/kixfw/content/][kixfw]]''' perl CGI script.
156:
157: To test the KIX installation simply type the configured KIX URL in your
158: favourite browser and you should be invited to a KIX login. However, login
159: is not supported, until the '''login''' CGI script has been installed
160: (see below).
161:
162: |
163:
164: '''Trouble Shooting KIX and Other CGI scripts'''
165:
166: When working with and developing CGI scripts it is often difficult to
167: understand why scripts sometimes don't work. This is particularly so
168: if you have no
169: access to the error log of the HTTP server
170: (which is often the case when a hosted HTTP service is used).
171:
172: It is then useful to wrap the CGI perl script using a simple
173: '''[[installation/dirs/cgi/wrapper/content/][wrapper shell script]]''',
174: which catches the errors and presents them in your browser window.
175:
176: Here are instructions on how to install such a
177: '''[[installation/dirs/cgi/wrapper/content/][wrapper shell script]]'''.
178:
179: |
180:
181: '''Creating a Password File in the etc Directory'''
182:
183: Before you can login to KIX you need to establish the KIX authentication.
184: If you intend to use KIX as it was distributed by MetaAgility
185: it is assumed that every KIX userid
186: is accompanied by a pair of userid and encrypted password in a
187: '''users''' file in the
188: '''[[installation/dirs/etc/content/][etc]]''' directory.
189:
190: There are many ways to establish such a file.
191: Here are instructions on
192: '''[[installation/dirs/etc/content/][how to do it]]'''
193: using the '''htpasswd''' utility (htpasswd is part of the apache distribution).
194:
195: |
196:
197: '''Installing the login and logout CGI Scripts'''
198:
199: Here are instructions on how to install the
200: '''[[installation/dirs/cgi/login/content/][login]]''' CGI script.
201:
202: And here are instructions on how to install the
203: '''[[installation/dirs/cgi/logout/content/][logout]]''' CGI script.
204:
205: The '''login''' and '''logout''' CGI scripts are the last items
206: required to fully operate KIX as a web user.
207:
208: After the first login to KIX it should be possible to see the user account
209: which was created by the '''init_kixfw''' script when the KIX database
210: was created (see above). This account is to be found in the '''users''' folder, which is the only subfolder to be found
211: in the otherwise empty top level KIX folder.
212:
213: |
214:
215: '''Installing the kix-regular Script and Configure cron jobs'''
216:
217: Here are instructions on how to install the
218: '''[[installation/dirs/etc/cron/content/][kix-regular]]''' cron job script.
219:
220: This script is used by KIX to send regular e-mails with summaries of KIX user
221: notifications. The script also performs deferred plugin actions as a result of
222: events received from remote dependency documents
223: in any configured KIX federation server.
224:
225: |
226:
227: '''Installing the kixshow CGI Script'''
228:
229: Here are instructions on how to install the
230: '''[[installation/dirs/cgi/kixshow/content/][kixshow]]''' CGI script,
231: which may be used by '''KIX admin users''' to view and patch
232: the low level content of the KIX database.
233:
234: |
235:
236: '''Installing the x3pkix CGI Server Script'''
237:
238: Here are instructions on how to install the
239: '''[[installation/dirs/cgi/x3pkix/content/][x3pkix]]''' CGI script.
240:
241: This script provides the KIX intallation with an X3P server,
242: which is used for KIX federation access. Since KIX
243: federations rely on the '''X3P''' peer-to-peer protocol such
244: federations cannot operate at all unless the
245: '''[[installation/dirs/cgi/x3pkix/content/][x3pkix]]''' script is configured.
246:
247: On the other hand if the KIX installation does not configure any federate
248: KIX servers the x3pkix script is not needed at all.
249:
250: |
251:
252: '''That's it - Enjoy Working with KIX'''
253:
254: KIX is a simple but serious tool for distributed engineering.
255: KIX real power only comes to light when it is extended by plugins which
256: targets the document types of one's working domain and
257: integrates KIX with one's working processes.
258:
259: There are a few generic KIX plugin's, which are distributed by MetaAgility
260: as open source:
261: * KixPlugin-Wiki2Html - transforms parts of a KIX repository to a distributed web content management system,
262: * KixPlugin-Export2File - simple integration tool which export KIX documents as external files,
263: * KixPlugin-DocReview - provides support for high precision distributed document reviews.
264:
265: See '''[[installation/plugins/content/][KIX plugins]]''' for starter instructions on how to extend KIX with these and other plugins.
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.