Kwatee Installation Guide version 2.3.0

Introduction

Kwatee is a web application packaged in a "war" package. As such, it works on any operating system with Tomcat and H2 (or mysql or postgreSQL).

It has been tested on MacOS, Ubuntu and Windows but will run on any other flavor of linux or unix as well.

In either case, Kwatee requires a proprietary and platform-specific agent (kwagent or kwagent.exe). At this time, there are agents for: 32 bits x86 linux, 64 bits linux, x86 and sparc Solaris, Windows, MacOS X and AIX.

Uploaded software packages and files are stored in the file system at a path that we'll refer to as kwatee.repositorydir that you configure during installation. Make sure that there is always enough available disk space on that partition

All other Kwatee data is stored in a SQL database.

The following users/roles will be needed to setup and configure Kwatee:

Tomcat process userthe user under which the tomcat process is running is only important to Kwatee insofar as he must have read/write privileges to kwatee.repositorydir.
Tomcat managerthis user is not mandatory but convenient for the installation/unistallation of the web application.
Database administratora sufficiently privileged user with database and user drop/create privileges is necessary on a first installation to create the kwatee database.
kwatee database userthis user, named kwatee by default, is created during the installation process. He will have full privileges on only the kwatee database.
default administratora default Kwatee user named admin with password password is created by default on the first installation.

There is also a command-line deployment tool, kwclideployer, which can be configured in a similar fashion to the web application but does not require a tomcat server.

Pre-requisites

Kwatee is not very resource intensive so there is no need to dedicate a full server, database engine or tomcat instance to it's operations.

Javaversion 1.5 or newer
Tomcatversion 5.5 or newer, only required for the web application. Actually, there is no reason it should not work with older versions. Other application servers have not been tested but may work.
DatabaseH2 (embedded). You may optionally use MySQL 5.1+ or PostgreSQL 8.4+ as well.

Installation

1. Deploy to tomcat

Expand the kwatee-webapp-distrib-2.3.0 archive.

Deploy kwatee-webapp-distrib/kwatee.war using Tomcat Manager.

2. Edit kwatee.properties

Edit tomcat_home/webapps/kwatee/WEB-INF/classes/kwatee.properties and customize the properties (see below)

PropertyDescription
kwatee.repositorydirthe path to the repository directory
kwatee.jdbc.schemathe name of the kwatee database
kwatee.jdbc.hostnamethe host on which the database server is running
kwatee.jdbc.driverthe database driver (org.H2.Driver or com.mysql.jdbc.Driver or org.postgresql.Driver)
kwatee.jdbc.userthe kwatee database user
kwatee.jdbc.passwordthe password of the database user
kwatee.jdbc.urlthe jdbc connection url whose format is specific to the jdbc driver
kwatee.conduit.serverFactoriescomma-separated list of fully qualified class names (see Installing a server pool factory)

The default kwatee.properties are suitable for an installation on a file-based H2 database:

kwatee.jdbc.user=kwatee
kwatee.jdbc.password=password
kwatee.jdbc.schema=kwatee
kwatee.jdbc.driver=org.h2.Driver
kwatee.jdbc.url=jdbc:h2:/var/kwatee/repository/db/kwatee

The properties below are suitable for an installation on a mysql database:

kwatee.jdbc.user=kwatee
kwatee.jdbc.password=password
kwatee.jdbc.schema=kwatee
kwatee.jdbc.driver=com.mysql.jdbc.Driver
kwatee.jdbc.url=jdbc:mysql://localhost/kwatee

The properties below are suitable for an installation on a postgresql database:

kwatee.jdbc.user=kwatee
kwatee.jdbc.password=password
kwatee.jdbc.schema=kwatee
kwatee.jdbc.driver=org.postgresql.Driver
kwatee.jdbc.url=jdbc:postgresql://localhost/kwatee

IMPORTANT: make sure that the tomcat user has filesystem privileges to write/create the kwatee.repositorydir or the web application will fail to start.

FOR WINDOWS: if you choose to replace default paths by windows paths, you must make sure to use double backslashes, i.e. kwatee.repositorydir=d:\\kwatee\\repository, or to replace them by forward slashes, i.e. kwatee.repositorydir=d:/kwatee/repository.

3. Setup Schema

install

Reload Kwatee using Tomcat Manager and then point your browser to http://kwatee.local:8080/kwatee/

The web interface will guide you through the steps for creating the database schema which will require you to supply a database user and password with sufficient privileges for creating users and a database.

Once this final step is completed, you'll see Kwatee's login screen. The default administrator user is admin with password password.

Advanced Configuration

Installing a Server Pool Factory

You can install additional server pool implementation such as the Amazon EC2 server pool which can be downloaded here.

Here is how you can install the EC2 server pool plugin after having downloaded it:

  1. Copy the ec2serverpool jar and its dependencies into the tomcat_home/webapps/kwatee/WEB-INF/lib/
  2. Edit tomcat_home/webapps/kwatee/WEB-INF/classes/kwatee.properties and add the property:
    kwatee.conduit.serverFactories=net.kwatee.agiledeployment.conduit.EC2ServerFactory
  3. Restart tomcat

The procedure is similar for other server pool types such as the ZK server pool.

Upgrading

The following procedure is recommended when upgrading to a new version of kwatee:

  1. Copy the configuration file tomcat_home/webapps/kwatee/WEB-INF/kwatee.properties to a temporary location.
  2. Undeploy Kwatee using Tomcat Manager
  3. Expand the kwatee-webapp-distrib package that you downloaded from kwatee.net
  4. Deploy kwatee-webapp-distrib/kwatee.war using Tomcat Manager.
  5. Overwrite the existing tomcat_home/webapps/kwatee/WEB-INF/kwatee.properties with the saved copy from step 1.
  6. Reload Kwatee using Tomcat Manager
  7. Point your browser to http://kwatee.local:8080/kwatee/