Check out the new projects site for A-i-S www.adventuresinsilicon.com

Sunday, July 3, 2011

HowTo: Run an OpenKM Server on PanadaBoard

This post assumes you are running Ubuntu on your Pandaboard and have access to the Internet Gateway sufficient to allow direct port access between your server and the Internet.

OpenKM is Knowledge Management software which stores files and your chosen metadata around those files.

It acts similar to Sharepoint in the way you can upload, check in, check out, lock documents etc. It has workflow management, search, etc etc



For more information about OpenKM see:

http://wiki.openkm.com/index.php/Main_Page

For a live demonstration you can play with go to:

http://demo.openkm.com/OpenKM/frontend/index.jsp


OpenKM will default to using port 8080. It runs a JBoss server and runs itself inside that.

To install OpenKM on your Pandaboard server following these steps:

STEP 1

Install openjdk on the Pandaboard.  Open a terminal on the Pandaboard (either locally or via ssh) and type:

sudo apt-get install default-jdk

STEP 1A (Optional for Previews)
This step is optional if you want OpenKM to display in-window previews of jpgs and pdfs
sudo apt-get install swftools imagemagick

STEP 2

Download the OpenKM files from:

https://sourceforge.net/projects/openkm/files/5.1/OpenKM-5.1.5_JBoss-4.2.3.GA.zip/download

The file is about 190Mb.

STEP 3
You now need to copy the downloaded file and unzip it.

I recommend unzipping it to the fastest disk available to the PandaBoard. I have an SD card and a USB Harddrive.  When I run it from the Harddrive I see twice the speed than running it on the SD card.

Once you have copied the file to the final location to run it from type the following at a console in that directory:

unzip OpenKM-5.1.5_JBoss-4.2.3.GA.zip

If the filename of the file you downloaded is different, use that instead of the filename above.

STEP 4
The next step is to test run the server. We will need to change a startup parameter for best performance on the PandaBoard.

By default the java server is allowed to access up to 1024 Mb of memory. I prefer to let it use only 512Mb as my kernel only exposes 728Mb due to the highmem bug for PandaBoards.

From the root directory you unzipped the downloaded file change directory into the jboss-4.2.3.GA or similar directory. Then change into the bin directory ( "/jboss-4.2.3.GA/bin" )

Then edit the "run.sh" file with nano by entering in the following command:

nano run.sh

Inside nano, amend the line near the top of the file which states:


"JAVA_OPTS="-Xms256m -Xmx1024m -XX:PermSize=64m..."

Change the reference to "-Xmx1024m" to "-Xmx512m"

Save the file by hitting "Ctrl-O"
Exit nano with "Ctrl-X"


OPTIONAL STEP 
If you opted to support previews in STEP 1A above then you need to edit OpenKM.cfg to tell OpenKM to enact the preview function. Do this by editing the "OpenKM.cfg" file in the "jboss-4.2.3.GA" (or similar) directory:
nano OpenKM.cfg

Inside that file remove the "#"s so it appears like:

#system.ocr=/usr/bin/tesseract
#system.openoffice.path=/usr/lib/openoffice
system.img2pdf=/usr/bin/convert
system.pdf2swf=/usr/bin/pdf2swf
#system.antivir=/usr/bin/clamscan
hibernate.dialect=org.hibernate.dialect.HSQLDialect
hibernate.hbm2ddl=create
#application.url=http://localhost:8080/OpenKM/com.openkm.frontend.Main/index.jsp


STEP 5
Now you are ready to run the server and test it.

In a console run the "run.sh" script by running the following from your jboss-4.2.3.GA directory:

"./bin/run.sh"


You should see lots of information being displayed on the screen and within 3-6 minutes a line telling you the server is started.

You can go to http://localhost:8080/OpenKM to test it.

Login with:
User:          okmAdmin
Password:   admin


STEP 6

Next we will stop the server and turn off the automatic database configuration when it runs so that the infomation you save in the database is not lost (users etc).

Make sure you are in the window in which you ran the server and press "Ctrl-C"

Then in your terminal window change directory to "/opt/jboss-4.2.3/" and edit the OpenKM.cfg file with:

sudo nano OpenKM.cfg


Now change the line about hbm2ddl:

hibernate.hbm2ddl=create
so that it becomes:
hibernate.hbm2ddl=none


STEP 7
Now we will configure Ubuntu to start it everytime the machine is started.

Now we will edit the startup scripts to automatically start the OpenKM server everytime the machine is started.

Inside your /etc/init.d/ directory create a file called "jbossokm" and add the following to the file:

#!/bin/sh
# /etc/init.d/jbossokm: Start and stop JBoss Application Service
### BEGIN INIT INFO
# Provides:        OpenKM
# Required-Start:   
# Required-Stop:   
# Default-Start:    2 3 5
# Default-Stop:       
# Short-Description:    OpenKM
### END INIT INFO


ECHO=/bin/echo
TEST=/usr/bin/test
JBOSS_START_SCRIPT=/media/restore/DingoNet/jboss-4.2.3.GA/bin/run.sh
JBOSS_STOP_SCRIPT=/media/restore/DingoNet/jboss-4.2.3.GA/bin/shutdown.sh


$TEST -x $JBOSS_START_SCRIPT || exit 0
$TEST -x $JBOSS_STOP_SCRIPT || exit 0
   
start() (
$ECHO "Starting JBoss OKM."
rm -rf /path/to/server/default/tmp
rm -rf /path/to/server/default/work
rm -rf /path/to/server/default/log
su -l -c "$JBOSS_START_SCRIPT -b 0.0.0.0 > /dev/null 2> /dev/null &"
$ECHO "Done."
)
   
stop () (
$ECHO "Stopping JBoss OKM. "
su -l -c "$JBOSS_STOP_SCRIPT -S > /dev/null &"
sleep 10
$ECHO "Done."
)
   
case "$1" in
start )
start
;;
stop )
stop
;;
restart )
stop
sleep 30
start
;;
* )
$ECHO "Usage: jbossokm {start|stop|restart}"
exit 1
esac
exit 0



Now edit the properties of the script file so it can be executed:
sudo chmod 0755 /etc/init.d/jbossokm

Run this command so that Ubuntu knows to start the script every time the Operating System starts.
sudo update-rc.d jbossokm defaults


Now start the service by running
sudo /etc/init.d/jbossokm start


The service can be stopped with:

sudo /etc/init.d/jbossokm stop

The service will start every time the machine is started now.


NEXT STEPS
See the OpenKM forum and community documentation on how to use it.  You will want to set up user accounts etc.

If you want to allow access over the Internet then you will want to punch a hole through your filewall for the port and probably use a redirection service like dyndns to maintain a static address.

Useful links for this topic:
 
Adding OpenOffice previews in the client:
http://www.openvpms.org/documentation/install-openoffice-headless-service-ubuntu


For installing Java see:
https://wiki.ubuntu.com/LucidLynx/ReleaseNotes#Sun%20Java%20moved%20to%20the%20Partner%20repository

No comments: