Debian 4 Installation Instructions
From KnowledgeTree Document Management Made Simple
Debian 4 (Etch) was released in 2007.
There are plenty of docs around on how to install this distribution, so this guide assumes you have some familiarity with Debian, and not much familiarity with KnowledgeTree.
Contents |
Context
You may be here because you were unsatisfied with the vanilla KnowledgeTree 'stack' installation - the 380MB behemoth that attempts to be All Things To All People <tm>. If you're a Debian user, and you attempted to install that package, you were probably surprised to discover that it is bundled with its own instances of MySQL, Apache, PHP, and so on. Not an optimum approach for anyone keen on easing maintenance or improving security (ie. your average Debian user) or anyone keen on using their GNU/Linux box for more than one task (ie. everyone (including your average Debian user)).
The guide here is for a pretty bog standard instance of Debian - it was written in 2008-06, when the stable branch of Debian was at version 4.1. Where it diverges from 'standard KT practice' these changes are highlighted so you can decide which approach you prefer.
Prepare for installation (grab some packages)
A heads-up on some requisite packages, though, as the usual dependency checking won't save you with this source-package installation of KnowledgeTree and you will get weird errors later if the following packages aren't installed up front.
This apt-get line is shown in case you want to save yourself some typing:
# apt-get install apache2 php5 php5-curl php5-mysql mysql-server mysql-client xpdf zip unzip catdoc pstotext
You may want to utilise mysql-server running on a remote box - this will work fine, but you'll have to adapt the following instructions to point away from localhost, and permissions for the dms database account will also need to be adjusted slightly. This is assumed knowledge for anyone who runs their own MySql host, but we'll get to these presently.
Grab and unpack the source, Luke
Find it
Sourceforge hosts the source files for KnowledgeTree. Their URL's change periodically so your best bet is to head to the http://sourceforge.net/ and search on 'knowledgetree'. Once there, hit the Download tab - this should take you to [[1]] but you never know.
In any event you are looking for the KnowledgeTree STABLE 3.5.2c (this version may well have changed by the time you read this). Follow the DOWNLOAD link to the right of this entry.
You're presented with a list of files -- you want the Platform-independent source tarball - it'll have 'src' and 'oss' in the name and end with 'tgz'. Download it.
Extract it
Move the tarball somewhere convenient (your home directory, say) and unpack it - note that the filename may be slightly different for you:
# tar xfz ktdms-src-oss-3.5.2c.tgz
This will create a directory called KnowledgeTree-OSS with about 40MB of content.
Relocate that directory to /var/www/ -- I like to rename it to something easier to type in the URL later. If you're going to have this running on a box that runs nothing else (web-wise) then move it to the docroot. Alternatively you may be using Apache's vhost capabilities. Again, use your initiative here.
For a bog standard approach, to be accessed later by a URL of http://yourserver/knowledgetree use:
# mv KnowledgeTree-OSS /var/www/knowledgtree
OR for a docroot approach use:
# mv KnowledgeTree-OSS/* /var/www/
Next we need to change the ownership of these files to the Apache user.
This is an essential step. (Adjust it to suit the location decided by the previous step)
# chown -R www-data:www-data /var/www/knowledgetree
Database magic
Account and database creation
Some familiarity with MySQL is assumed, but all we need to do is create one database, one or two accounts, and then grant rights to that db.
The 'one or two' accounts decision comes down to whether you want a separate dms and dmsadmin account with different rights to the dms database. I prefer fewer accounts as I think this improves security (and having DELETE rights to the database is functionally the same as being able to DROP it anyway), but you may prefer more accounts with finer granularity of rights. The KT default is two accounts.
One account approach
We'll call the account dms and it will have full rights to the dms database. We just need to create the database, account and then change the config file. We assume here that you have a MySQL root password and that you know what it is.
# mysql -u root -p Enter password: mysql> create database dms; mysql> grant all on dms.* to 'dms'@'%' identified by 'bigsecretpassword'; mysql> flush privileges; mysql> exit;
And then we change the configuration file - specifically the config/config.ini file. Open up this text file with your favourite editor and make three changes:
dbPass = 'bigsecretpassword' dbAdminUser = dms dbAdminPass = 'bigsecretpassword'
You may need to change dbHost if you're using a remote MySQL server - you're on your own with this one.
Two accounts approach
The two accounts are dms and dmsadmin - the former has SELECT, INSERT, UPDATE and DELETE rights, and the latter has ALL PRIVILEGES, to the dms database. This is specified in the SQL script user.sql which lives in the sql/mysql/install directory, but we'll avoid using this file later.
# mysql -u root -p Enter password: mysql> create database dms; mysql> grant SELECT, INSERT, UPDATE, DELETE on dms.* to 'dms'@'%' identified by 'bigsecretpassword'; mysql> grant all on dms.* to 'dmsadmin'@'%' identified by 'reallybigsecretpassword'; mysql> flush privileges; mysql> exit;
And then we change the configuration file - specifically the config/config.ini file. Open up this text file with your favourite editor and make two changes:
dbPass = 'bigsecretpassword' dbAdminPass = 'reallybigsecretpassword'
You may need to change dbHost if you're using a remote MySQL server - you're on your own with this one.
Import the KnowledgeTree schema
Go to the sql script directory - it's located at sql/mysql/install from the docroot.
We need to run two scripts - the first installs the schema, the second populates it with some default data. We do not run the usual third script, as we've already create the user(s) in the previous step. You'll obviously be prompted for the MySQL root password for both these steps:
# mysql -u root -p dms < structure.sql # mysql -u root -p dms < data.sql
Just before you use your new site
Configure email transport
Edit the config/config.ini file and change the following two lines:
emailServer = emailFrom =
The former should be set to your SMTP smarthost that routes all your email.
The latter should be set to a valid email address that users can reply-to later on (it will present as the 'From' address for emails coming from the server). You may also want to change the emailFromName to something more aligned to your business processes.
Configure docroot
The system is meant to automatically identify the 'docroot' but tends not to.
Modify the config/config.ini file, specifically the rootUrl line, as per the location decision you made way back up the top of this guide. If it's in the root (/var/www) then you're fine to leave it blank.
rootUrl = /knowledgetree
Note that some weird errors may occur if this is not root (f.e. the Refresh link on the Document Indexer Status section of the Dashboard will ignore this setting). It appears to be ignoring the kt_url() function that, seemingly, grabs and retains the above setting at login time (rather than on each page refresh). More investigation required.
Configure PHP
You probably also want to change the memory_limit setting of your PHP. Out of the box this is set to 16MB, but this is nowhere near enough for Knowledgetree - change it to something decent (say 64MB).
Edit /etc/php5/apache2/php.ini
memory_limit = 64
And of course restart apache:
# /etc/init.d/apache2 restart
Grab a few more packages
There's a few things that KnowledgeTree likes to have available. Some of these I haven't worked out how to get going yet:
- Openoffice-Server (a daemon) - not much documentation on doing this, but it looks like soffice --invisible requires java, and seemingly not Sun Java 5,
- Document Indexer - not much documentation on how to crank this thing up either
But there are a few things that we (probably) need, so let's grab them first. The python/uno stuff is for converting MS-Word/Excel documents (and presumably .ODx files) to PDF's - this will pull a lot of OpenOffice down as dependencies. The antiword application is also used for extracting MS-Word documents. Sun's Java5 is required for running the indexing server (Lucene). Lynx is needed for the scheduler which we'll plug in to cron.
# apt-get install python-reportlab python-imaging python-uno antiword sun-java5-jre sun-java5-bin lynx openoffice.org-java
Set up cron job (scheduler)
The official documentation (2008-04-11) mistakenly sets up the crontab to run every hour at one minute past the hour, while asserting that it should run every minute. Running this every minute is probably a bit onerous for the server, but it comes down to what performance you want compared to what delay your users will cope with. I'll assume an 'every 5 minutes' run for the scheduler, but you can easily change this to something else.
Create the file /etc/cron.d/knowledgetree. Again, some initiative is required here, specifically for the path to the scheduler.php file
# /etc/cron.d/php5: crontab fragment for knowledgetree # # This will launch lynx against the scheduler php page - this # will show up in the apache logs as a hit against that page. */5 * * * * root lynx -dump http://localhost/knowledgetree/bin/scheduler.php
If you do want this to run every minute, simply change the */5 to *
Set up the Indexer
KnowledgeTree uses the Lucene server, which is bundled with even this basic source package.
The official documentation [paraphrased] correctly asserts that you can launch this with:
cd /var/www/knowledgetree/bin/luceneserver nohup java -jar ktlucene.jar &
However this will generally fail due to an exuberance of ../'s in the KnowledgeTreeIndexer.properties located in that directory. It attempts to traverse up three directories and back into var - but it really only needs to go up two directories. Change the file KnowledgeTreeIndexer.properties to reflect:
indexer.directory=../../var/indexes
This configuration file also ASSUMES that you have a local network of 192.168.1.0/24 AND that you want everyone on that network to be able to use the indexing service. You may want to remove, or at least modify the server.accept= line in that same configuration file.
You can run the above command without the nohup the first time to make sure that it works. After that you'll want to have this launch at boot - look at creating your own /etc/init.d/luceneindexer script and then enabling it with update-rc.d
You can Debian's skeleton file in /etc/init.d - this is easiest if you delegate the launch to a script located elsewhere - I prefer /usr/local/sbin
As an example, here's what I've done:
# cp /etc/init.d/skeleton /etc/init.d/knowledgetreeluceneindexer
Edit /etc/init.d/knowledgetreeluceneindexer and change the top bit to look like this:
PATH=/sbin:/usr/sbin:/bin:/usr/bin DESC="Lucene indexer for KnowledgeTree" NAME=knowledgetreeluceneindexer
Create the thing that does the actual launching - edit /usr/local/sbin/knowledgetreeluceneindexer :
#!/bin/bash cd /var/www/knowledgetree/bin/luceneserver/ java -jar ktlucene.jar &
Force this to run at boot, as per the default init.d script:
# chmod 755 /etc/init.d/knowledgetreeluceneindexer /usr/local/sbin/knowledgetreeluceneindexer # update-rc.d knowledgetreeluceneindexer defaults
You can test this with the following command, and also you should reboot to ensure it starts okay at power-on.
# /etc/init.d/knowledgetreeluceneindexer start
Set up the OpenOffice Server
This, despite suggesting that it can run 'headless' and 'invisible', actually does require an X server to be running. You can use the fake one - xvfb (note that the official documentation has misspelt this as 'xvbf'). This X server in turn needs the usual guff for running X - specifically lots of fonts - akin to trying to get VNC running. The following should be sufficient:
# apt-get install xvfb xfonts-base # Xvfb -screen 0 800x600x16 & # export DISPLAY=localhost:0 # soffice -headless -invisible -accept='socket,host=localhost,port=8100;urp' &
This still fails with a 'javaldx can't find runtime' error, but soffice does actually launch and stays running in the background, and KnowledgeTree believes that it's running (though it doesn't actually work properly). javaldx is available at:
- /usr/lib/openoffice/program/javaldx
Running this, even with a commandline like this, fails with a 'Could not find a JRE' error:
set LD_LIBRARY_PATH=/usr/lib/jvm/java-1.5.0-sun/jre/lib/i386/client/ ; /usr/lib/openoffice/program/javaldx
By changing config/config.ini you can point your KT installation to use a remote server's instance of OpenOffice - these settings are made in the [openoffice] section of this configuration file.
And of course you want to set this up similar to the Lucene Indexer above - such that it runs at boot.
As an example, here's what I've done:
# cp /etc/init.d/skeleton /etc/init.d/knowledgetreeoofficeserver
Edit /etc/init.d/knowledgetreeoofficeserver and change the top bit to look like this:
PATH=/sbin:/usr/sbin:/bin:/usr/bin DESC="OpenOffice Server for KnowledgeTree" NAME=knowledgetreeoofficeserver
Create the thing that does the actual launching - edit /usr/local/sbin/knowledgetreeoofficeserver :
#!/bin/bash Xvfb -screen 0 800x600x16 & export DISPLAY=localhost:0 soffice -headless -invisible -accept='socket,host=localhost,port=8100;urp' &
Force this to run at boot, as per the default init.d script:
# chmod 755 /etc/init.d/knowledgetreeoofficeserver /usr/local/sbin/knowledgetreeoofficeserver # update-rc.d knowledgetreeoofficeserver defaults
You can test this with the following command, and also you should reboot to ensure it starts okay at power-on.
# /etc/init.d/knowledgetreeoofficeserver start
The Knowledge Tree scheduler includes a job to periodically check for availability of the OpenOffice server, restarting it automatically in case of a crash. As of KT 3.5.2c, this feature works only for stack installations; to have it working for source installations, you have to patch the file /bin/checkopenoffice.php in the following way, changing line 120:
$sPath = realpath('../../dmsctl.sh');
and fixing the path to the actual OpenOffice init script; in this case:
$sPath = realpath('/etc/init.d/knowledgetreeoofficeserver');
Visit your new site and login
At this point your new KnowledgeTree site should be up and running.
Visit the server ( something like http://yourserver/knowledge - but this depends on your configuration choices above).
You'll be redirected to the KnowledgeTree login page, where you need to use the default admin credentials of:
- user: admin
- password: admin
Obviously you want to be changing that password as soon as possible.
del.icio.us
digg
reddit
facebook
stumbleupon
