Quick installation and upgrade overview

This chapter gives a brief overview of the installation or upgrade of an iKnowBase instance.

The process typically have the following steps:

• Download the software onto your application server
• Use the quickstart program to install or upgrade the database repository
• If you don’t want to use the quickstart web server, install the new or updated web applications into the proper application server

Download and install the iKnowBase software

Directory structure

We strongly recommend that you choose a server for storing the iKnowBase software and running the installation. In most scenarios this server would be a server where the web applications will run. Here, install into a directory structure similar to the one below, with one directory for each version the actual distribution (named after the distribution version) and one directory for each iknowbase installation (each database repository):

/opt/iknowbase                          # This is the root install directory
/opt/iknowbase/iKnowBase-6.4            # iKnowBase version 6.4
/opt/iknowbase/iKnowBase-7.0            # iKnowBase version 7.0
/opt/iknowbase/dev                      # Configuration for the development-environment
/opt/iknowbase/test                     # Configuration for the test-environment
/opt/iknowbase/prod                     # Configuration for the production-environment

Download and install the software

Using the recommended directory structure above, install the iKnowBase software into the proper location.

$ cd /opt/iknowbase
$ #...copy the software to /opt/iknowbase...
$ unzip iKnowBase-7.0-Quickstart.zip

Configure the repository-specific property file

You will typically have multiple iKnowBase repositories in a single database, to handle different phases in the life cycle, such as development, testing and production. We recommend that you set up a directory for each such repository, where you store configuration files, log files, etc.

For each repository, create a property file with all the required settings for connecting to the database and running the embedded web server. The name can be generic (“iknowbase.properties”) or environment specific (“iknowbase-test.properties”), but that is entirely up to you. Edit the file, and set proper values for db.URL, db.sysPassword, db.ikbUser and db.ikbPassword.

• db.URL is the jdbc url to the database on the form "jdbc:oracle:thin: //hostname:port/instance-name", it could typically be something like "jdbc:oracle:thin://localhost:1521/ORCL".
• db.sysPassword is the password for the SYS-user in the database.
• db.ikbUser is the name of the database user that contains the iKnowBase repository that will be upgraded.
• db.ikbPassword is the password for the iKnowBase database user.

A minimal file could look like this:

db.URL = jdbc:oracle:thin:@//localhost:1521/orcl
db.sysUser = sys
db.sysPassword = secret_password_for_sys_user
db.ikbUser = iknowbase
db.ikbPassword = secret_password_for_iknowbase_user

For simplicity, and to avoid accidentally using the wrong version of the quickstart program, we also recommend creating a “quickstart.sh” script that forwards to the proper version:

cat >quickstart.sh
#!/bin/bash
../iknowbase-6.4/quickstart.sh $*

Install or upgrade the database repository

To install a fresh iKnowBase repository, run the following steps:

$ cd /opt/iknowbase/dev
$ ./quickstart.sh iknowbase.properties createUser
$ ./quickstart.sh iknowbase.properties uploadFile IKB_MASTER.DATA
$ ./quickstart.sh iknowbase.properties importFile IKB_MASTER.DATA IKB_MASTER
$ # Optionally download and display import log
$ ./quickstart.sh iknowbase.properties downloadFile IKB_MASTER.DATA.LOG
$ cat IKB_MASTER.DATA.LOG
$ # Run upgrade scripts on the newly created installation
$ ./quickstart.sh iknowbase.properties upgradeAll
$ ./quickstart.sh iknowbase.properties upgradeActivitiSchema

To upgrade an existing iKnowBase repository, run the following steps instead:

$ ./quickstart.sh iknowbase.properties exportSource source.zip
$ ./quickstart.sh iknowbase.properties configureUser
$ ./quickstart.sh iknowbase.properties upgradeAll
$ # If you have activiti installed, you need to upgrade it
$ ./quickstart.sh iknowbase.properties upgradeActivitiSchema

If you have any custom scripts that need to run, for example to grant permissions to custom code, run these now.

Install and run web applications

With the database repository in place, you can run the iKnowBase web applications. There are two main alternatives: Either use the embedded iKnowBase web server, or deploy to one of the supported application servers.

Note that it is often advisable to configure the quickstart embedded web server even when you will be installing into a full application server, as this is useful for testing and troubleshooting.

Embedded web server

The embedded web server, is run using the quickstart command. It uses an internal user repository (for usernames and passwords), so you will have to set the password before starting it the first time. Use the following steps to set password and start the web server:

# Set password only if needed (typically on fresh install)
$ quickstart.sh iknowbase.properties setIkbPassword orcladmin mypassword
$ quickstart.sh iknowbase.properties webServer

This will bring up the iKnowBase Quickstart web server, listening on port 8080 on the machine where the program is running. If this is on your local computer, start a web browser and point to "http://localhost:8080/xnext/accesspage/frontpage"

Java Application Server

To run iKnowBase on one of the supported application servers, you need to deploy the web applications there. The actual commands and mechanisms used for this varies from application server to application server, but can be summarized as follows:

First, decide which applications to install. A full installation comprises the application archives shown below, but you may choose to install only a subset of these if you want.

• iknowbase-activitiexplorer-webapp-VERSION.war
• iknowbase-batch-webapp-VERSION.war
• iknowbase-instant-webapp-VERSION.war
• iknowbase-processervicesws-webapp-VERSION.war
• iknowbase-resources-VERSION.war
• iknowbase-sandbox-security-webapp-VERSION.war
• iknowbase-studio-webapp-VERSION.war
• iknowbase-viewer-webapp-VERSION.war
• iknowbase-webdav-webapp-VERSION.war
• iknowbase-webservices-webapp-VERSION.war

• Before deployment, you will need to configure a data source named “jdbc/iknowbaseDS”, pointing to the iKnowBase database with the iKnowBase user where the database schema was installed. The data source need to be connection pooled, so for many application servers you first create a connection pool pointing to the database schema, and then a data source pointing to the data source.
• You will typically deploy the applications under the paths /ikbStudio, /ikbViewer, /ikbBatch, /ikbWebdav, /ikbWebServices and /ikbInstant.
• During deployment, you will need to configure security settings for the applications. The mechanism for this is application server specific, but the principles are always the same:
  • The role “IKB_USERS” should be assigned to all users that may use iKnowBase. While some content is available without logging in, only users that are assigned this role (directly or indirectly) will have access to protected content.
  • The role “IKB_DEVELOPERS” should be assigned to all users that will build applications using iKnowBase.
  • The role “IKB_SYSADMINS” should be assigned to all users that will manage the iKnowBase installation.

The instructions above deploys the iKnowBase static resources (the “/ressurs” directory) on the application server. Often, you will want to deploy these on a separate web server in front of the application server. The mechanism is typically as follows:

• Unzip the file “iknowbase-resources-VERSION.war” into a directory of choice
• Mount that directory as “/ressurs” in your web server.