Kapow Mashup Server 6.

Installation Guide

Installation Guide

Copyright 1999-2007 Kapow Technologies http://www.kapowtech.com All rights reserved.

CONTENTS

iii

Contents
INTRODUCTION ........................................................................................ 5 Other Resources .................................................................................5 INSTALLING KAPOW MASHUP SERVER ........................................................... 6 Installing on Windows .........................................................................6 Installing from a CD-ROM..................................................................6 Installing from a Downloaded Installer ................................................6 Installing on Linux ..............................................................................6 Installing from a CD-ROM..................................................................6 Installing from a Downloaded Installer ................................................6 Installing on a Headless Computer......................................................7 Silent Installation ...............................................................................7 Important Folders in Kapow Mashup Server ............................................7 CONFIGURING KAPOW MASHUP SERVER ......................................................... 9 Setting the Current Robot Project........................................................ 10 Configuring the Database Connections ................................................. 10 Setting up the Object Databases ...................................................... 10 Setting up the RoboManager Databases ............................................ 10 Configuring the Database Connections .............................................. 11 Specifying a Proxy Server .................................................................. 15 Configuring the Web Server ............................................................... 16 Enabling Administration Security ...................................................... 16 Setting Up a Cluster of RoboServers ................................................. 16 Running RoboServer as a Service........................................................ 16 Configuring the Bug Reporting ............................................................ 17 Changing the License Information ....................................................... 17 Installing New Certificates.................................................................. 17 UPGRADING FROM EARLIER VERSIONS ......................................................... 19 Upgrading Clipping Robots and Portlets................................................ 19 INDEX.................................................................................................. 20

INDEX

Introduction
This Installation Guide describes how to install Kapow Mashup Server.

Other Resources
Further information on installing Kapow Mashup Server may be available from the support site at this URL: http://support.kapowtech.com/ For information on using Kapow Mashup Server, refer to the Users Guide for each application.

INSTALLATION GUIDE

Installing Kapow Mashup Server

This Installation Guide covers installation on Windows and Linux. If you need to install Kapow Mashup Server on other platforms, please refer to the support site at the URL given in the section Other Resources.

Installing on Windows
Note: You need to have administrator rights to install on Windows.

Installing from a CD-ROM

When you insert the CD-ROM, the installation program will start automatically. Follow the instructions in the program. If the installation program does not start automatically, run the setup.exe file on the CD-ROM.

Installing from a Downloaded Installer

You will have received instructions on how to download the installer. Download and save the setup.exe file to your hard disk. After the download is completed, run the file to start the installation.

Installing on Linux
Note: You should install as an unprivileged user on Linux.

Installing from a CD-ROM

To install Kapow Mashup Server, insert the CD-ROM and mount it. Usually, the mounting is done like this: #cd /mnt #mount cdrom Note: You may need to be root to mount the CD-ROM. After this, start the installation program as follows: #cd /mnt/cdrom #sh setup.bin Then, follow the instructions in the installation program.

Installing from a Downloaded Installer

You will have received instructions on how to download the installer. Download and save the setup.bin file to your hard disk. After the download is completed, start the installation as follows: #sh setup.bin Then, follow the instructions in the installation program.

INDEX

Installing on a Headless Computer

If you are installing on a headless computer (a computer without an X window system) you can install using the console installer. The console installer is included in the standard installer; you start the headless installation program as follows: #sh setup.bin i console This applies to both the CD-ROM and the downloadable installer.

Silent Installation
A silent installer is able to run without user interaction. This is handy if you need to automate the installation process in a script. To utilize the silent installer, you need to create an ASCII text file containing parameters for the installer. The file should contain the following: INSTALLER_UI=silent USER_INSTALL_DIR=[Path to installation folder] LICENSE_NAME=[Your name] LICENSE_EMAIL=[Your email] LICENSE_COMPANY=[Company name] LICENSE_KEY=[License key] You can omit the line containing the USER_INSTALL_DIR to install in the default folder. Save the file as installer.properties. It is important that this file is placed in the same folder as the installer file (setup.exe or setup.bin). Now launch the installer as usual and it will detect the file and run in silent mode.

Important Folders in Kapow Mashup Server

There are a few folders and files in the installation that you need to know about. The installation folder is the folder where Kapow Mashup Server is installed. On Windows, the installation folder defaults to: C:\Program Files\Kapow Mashup Server 6.4 On Linux, it defaults to: ~/Kapow_Mashup_Server_6.4 The installation folder contains the following important folders: bin contains all executable programs for Kapow Mashup Server. Project a default robot project created by the installation. See the RoboMaker Users Guide for more information on robot projects. Documentation contains documentation, such as the Users Guide for each application. API contains files and documentation related to the Kapow Mashup Server Integration APIs.

INSTALLATION GUIDE Certificates contains the HTTPS certificates known by Kapow Mashup Server. See the Installing New Certificates section for more information. Plugins contains the Kapow Mashup Server plugins. lib/jdbc contains the installed JDBC database drivers. See the Configuring the Database Connections section for more information on installing new JDBC drivers.

INDEX

Configuring Kapow Mashup Server

After installing Kapow Mashup Server, you should configure the installation to suit your needs. Most of this configuration is done using the Settings application, shown below:

Figure 1: Settings Main Window Using this application, you can configure the following: The location of the current robot project. The connections to databases that Kapow Mashup Server should be able to access. The proxy server that Kapow Mashup Server should use, if any. The use of certificates. The parameters to RoboServer when run as a service. The embedded Web Server. The bug reporting. The license information.

After changing any of the settings in Settings, you should click OK to store the new settings, and then restart all other applications that you have running, to make the changes take effect. You may also want to install additional certificates or change the certificates that are included by default. See the section Installing New Certificates.

10

INSTALLATION GUIDE

Setting the Current Robot Project

You can set the location of the current robot project folder in the Project folder of Settings. By default, the folder will be set to the default robot project created in the installation folder by the installation process. See the RoboMaker Users Guide for more information on robot projects.

Configuring the Database Connections

If you plan to use databases together with Kapow Mashup Server, you need to configure the connections between Kapow Mashup Server and the databases. Kapow Mashup Server can use two kinds of databases: An object database a database for storing output objects extracted by Kapow Mashup Server. You need such a database only if you want to store the output objects in a database. (Do not confuse the term object database with the term object-oriented database. In Kapow Mashup Server, an object database is an ordinary relational database that Kapow Mashup Server uses for storing objects.) A RoboManager database a database for storing administrative information. You need this database only if you want to use the RoboManager application of Kapow Mashup Server.

The databases are independent of each other and do not have to be placed on the same database server. You can have multiple object databases and RoboManager databases this may be especially useful for running simultaneous test and production environments. See the release notes for a complete list of supported databases.

Setting up the Object Databases

To use one or more object databases, you must prepare your database server by either creating the new databases, or simply making sure that existing databases are available. For each object database you intend to use, you must obtain a username and password with rights to select, insert, and update in the database. After setting up the object databases, configure the connections to them as described in the section Configuring the Database Connections below. After configuring the connections, you can use the ModelMaker application to create tables for the objects that you want to store in the databases. In this case, the database users should also have rights to create and drop tables. See the ModelMaker Users Guide for how to create the tables.

Setting up the RoboManager Databases

To use one or more RoboManager databases, you must prepare your database server by either creating the new RoboManager databases, or simply making

INDEX

11

sure that existing databases are available. For each RoboManager database you intend to use, you must obtain a username and password with rights to create tables, drop tables, create indexes, drop indexes, select, insert, update, and delete in the database. After setting up the RoboManager databases, configure the connections to them as described in the section Configuring the Database Connections below. After configuring the connections, the required tables in the databases can be created by starting the RoboManager application it will guide you through the process.

Configuring the Database Connections

For each database that Kapow Mashup Server should be able to use, you must configure a connection from Kapow Mashup Server to the database. This is done in the Database Connections tab of the Settings application, shown in Figure 2.

Figure 2: Configuring Database Connections in Settings In the left side of the window is a list of the created connections. You can create new connections, remove connections, or change their order, using the buttons below the list. The currently selected connection is configured in the right side of the window.

12 A connection is configured using the following properties: Property Database Name Description

INSTALLATION GUIDE

The name of the database as seen from inside Kapow Mashup Server. Note that this is different from the Host Database Name below, although you can use the same name here if desired. The type of database, e.g. Oracle. The host name of the database server. This can be an IP-address, or the fully qualified domain name, e.g. myhost.kapowtech.com. The name of the database on the database server. The user name for the database. The password for the database. The port number on the database server. Leave it blank to use the default port number for the database type that you have selected. If the database uses a special character encoding you can enter the encoding here. Please refer to your database documentation for information on the name of the encoding. The maximum number of concurrent connections to the database.

Database Type Host

Host Database Name User Name Password Port Number

Character Encoding

Max Concurrent Connections

You can test the current connection by pressing the Test Connection button. Note: This will only test the connection to the database, it will not test that you have the proper permissions in the database. Connecting to Oracle: If you are using an Oracle database, you need to enter a user name and a role in the User Name property. For example, if the user name is sys, and the role is sysdba, you should enter sys as sysdba in the User Name property. Connecting to DB2: To connect to your DB2 database, you need to start a special server on the database server one which enables Java programs to connect to the database. To start the server, locate the file named db2jstart on the database server, and start it with the command db2jstrt 6789. You are also required to install the JDBC driver for DB2. The JDBC driver is

INDEX

13

included in your database installation. Look for a file called db2java.zip. When connecting to version 8.2 you should also copy db2jcc.jar. You must copy that file to your installation. On Windows, the default destination directory is: C:\Program Files\Kapow Mashup Server 6.4\lib\jdbc\ On Linux, the default destination directory is: ~/Kapow_Mashup_Server_6.4/lib/jdbc/ Connecting to Microsoft SQL Server 2005: To connector to your Microsoft SQL Server 2005, you must download the SQL Server 2005 JDBC driver from http://www.microsoft.com. The download contains a file named sql2005jdbc*.jar. You should copy this file to your installation. On Windows, the default destination directory is: C:\Program Files\Kapow Mashup Server 6.4\lib\jdbc\ On Linux, the default destination directory is: ~/Kapow_Mashup_Server_6.4/lib/jdbc/ Connecting to Microsoft SQL Server 2000: To connect to your Microsoft SQL Server 2000, you must download the Microsoft SQL Server 2000 Driver for JDBC from http://www.microsoft.com. The download contains three files named msbase.jar, mssqlserver.jar, and msutil.jar. You must copy these files to your installation. On Windows, the default destination directory is: C:\Program Files\Kapow Mashup Server 6.4\lib\jdbc\ On Linux, the default destination directory is: ~/Kapow_Mashup_Server_6.4/lib/jdbc/ Connecting to Microsoft SQL Server 7.0: To connect to your Microsoft SQL Server 7.0, you must buy the Sprint driver from i-net software http://www.inetsoftware.de/English/produkte/JDBC2/Default.htm. It is possible to download a trial version. The download contains a file named Sprinta2000.jar. You must copy that file to your installation. On Windows, the default destination directory is: C:\Program Files\Kapow Mashup Server 6.4\lib\jdbc\ On Linux, the default destination directory is: ~/Kapow_Mashup_Server_6.4/lib/jdbc/ Connecting to MySQL: To connect to your MySQL, you must download the MySQL JDBC driver (MySQL Connector/J) from http://www.mysql.com. The download contains a file named mysql-connector-java-*-bin.jar. You should copy this file to your installation. On Windows, the default destination directory is: C:\Program Files\Kapow Mashup Server 6.4\lib\jdbc\

14 On Linux, the default destination directory is: ~/Kapow_Mashup_Server_6.4/lib/jdbc/

INSTALLATION GUIDE

Connecting to PointBase Server: If you are using PointBase Server 4.3, you must either upgrade to version 4.4, 4.5, or obtain the latest 4.3 patch from PointBase. To connect to your PointBase Server, you must copy the PointBase JDBC driver from your database installation to your installation. The driver can normally be found in the PointBase installation directory, under lib. The file name is pbclient43.jar (for PointBase version 4.3), or pbclient44.jar (for PointBase version 4.4). Copy this file to your installation. On Windows, the default destination directory is: C:\Program Files\Kapow Mashup Server 6.4\lib\jdbc\ On Linux, the default destination directory is: ~/Kapow_Mashup_Server_6.4/lib/jdbc/

INDEX

15

Specifying a Proxy Server

In Settings you can specify a single proxy server that will be used by Kapow Mashup Server. If you want to use multiple proxy servers, this can be done by specifying a list of proxy servers in a file as detailed below. In the Proxy Server tab of Settings the proxy server is specified using the following properties: Property Use Proxy Server Host Description Check this checkbox to enable the use of a proxy server. The host name of the proxy server. This can be an IP address, or the fully qualified domain name, e.g. myproxy.kapowtech.com. The port number on the proxy server. Leave this blank to use the default proxy server port 8080. The user name to use if the proxy server requires login. The password to use if the proxy server requires login. Here, you can specify a list of host names that the proxy server should not be used for. You should specify one host name per line. Each host name can be an IP address, or a fully qualified domain name, e.g. www.kapowtech.com.

Port Number

User Name Password Excluded Hosts

Multiple proxy servers can be specified in the Configuration/proxyserver.properties file in the installation folder (if the file does not exist you can simply create it). The file consists of a number of proxy server entries, each of the form:

proxyName.proxyServerUse = true proxyName.proxyServerHost = host name or IP address proxyName.proxyServerPort = port number proxyName.proxyServerUserName = user name proxyName.proxyServerPassword = password proxyName.proxyServerExcludedHostNames = list of hosts
Where proxyName is a name chosen to identify that particular proxy server. Each proxy server must have its own unique proxyName.

16

INSTALLATION GUIDE

The file can be updated on-the-fly while Kapow Mashup Server is running. Kapow Mashup Server will check the file every minute and reload the proxy server settings if the file has changed. When multiple proxy servers are specified, a new proxy server will be chosen every time a robot is run. Note that you can also specify a proxy server for an individual robot. This is done when you configure the robot in the Robot Configuration Window in RoboMaker. Such a proxy server will override any proxy servers specified in Settings or the proxyserver.properties file. See RoboMaker Users Guide for more information.

Configuring the Web Server

The embedded web server is available in Kapow Mashup Server Web 2.0 Edition. It is started when RoboServer starts and exposes robots deployed from RoboMaker as services. By default, the web server will listen on port 50080. The services can be browsed on: http://host:50080/ The services can be administered on: http://host:50080/admin

Enabling Administration Security

The web administration interface can, by default, only be accessed from the localhost. By disabling the Administration Only From Localhost option you can allow access from remote machines. If you do this, you should also enable an administrator password. Select the Use Admin Password option and enter an administrator user name and password. You must use these credentials both when you publish a robot to the server from RoboMaker and when you access the administration interface from a browser.

Setting Up a Cluster of RoboServers

In a clustered setup a single web server delegates robot executions to a number of RoboServers. In the settings for the web server that will act as front end the list of RoboServers to use are configured. Each of these RoboServers will only be used to execute robots; their web servers will not be used. In fact, it is recommended that you start the additional RoboServers with the nowebserver option so that their web servers are not started.

Running RoboServer as a Service

You can run RoboServer as a service. On Windows, the installer automatically installs RoboServer as a service. Open the service overview (on Windows, this

INDEX is done by clicking Start/Settings/Control Panel/Administrative Tool/Services) and locate the RoboServer service. Right-click and select Properties to start, stop, and enable automatic startup. On Linux, you are required to write a simple wrapper around the RoboServerService executable in the installation folder. Place the wrapper wherever your Linux distribution normally has services. See your Linux documentation for more information on installing services. The parameters used by RoboServer when started as a service can be set under the RoboServer tab in Settings. The parameters are the same as you would use for RoboServer on a command-line. See the RoboServer Users Guide for more information.

17

Configuring the Bug Reporting

Kapow Mashup Server has a built-in mechanism for handling internal errors that occur during its operation. When an internal error occurs in a GUI-based Kapow Mashup Server application, the user will be able to send a bug report with details about the error. The user can also send a bug report on his own initiative, by selecting the Report Bug action from the Help menu. A bug report is sent as an email to the recipient specified in the Bug Reporting tab of Settings, using the specified mail server. You are encouraged not to change the default settings in this tab unless absolutely required.

Changing the License Information

In the License tab of Settings, you can change your license information. For example, you can specify a new license key if your current key has expired.

Installing New Certificates

Kapow Mashup Server includes several root certificates for use when loading from HTTPS sites. Some HTTPS sites may use certificate authorities that are not included by default. In this case, you need to install the appropriate certificates for Kapow Mashup Server to load from these sites. To install a certificate, you need to obtain the certificate as a PKCS#7 certificate chain, a Netscape certificate chain, or a DER-encoded certificate. To install a single server certificate, save the certificate in the Certificates/Server folder in the installation folder. To install a new root certificate, save it in the Certificates/Root folder in the installation folder. The name of the file containing the certificate does not matter. The following example explains how to install a server certificate for the website https://www.foo.com. The example is based on Internet Explorer 6. Open https://www.foo.com in Internet Explorer 6.

18

INSTALLATION GUIDE Select Properties under the File menu, and then select Certificates. This will open a Certificate dialog. Click Install Certificate. Click Next twice, Finish once, and exit the certificate dialog. Now you have installed the certificate in your browser. The next step is to export it to a file. Click Internet Options... in the Tools menu. This opens the Internet Options dialog. Go to the Content tab and click on the Certificates button. Now you need to locate the installed certificate. It is most likely in the tab called Other People. Select the certificate and press Export. Press Next twice. Save the certificate in the Certificates/Server folder in the installation folder as foo.cer. Restart all your Kapow Mashup Server applications.

Note: You must install the certificates on all installations that need to load from the particular HTTPS sites. Multiple client certificates can be installed in the Certificates tab of Settings. Unless a particular certificate is selected in a robot, the default certificate will be used. Only a robot configured to use Apache HTTP Client can take advantage of multiple certificates. To install a new client certificate press the plus sign. You will be prompted to select a certificate file which must be in PKCS12 format, and you must enter the password used to encrypt the file. Each client certificate must be given a unique ID which is later used in the robot to select the certificate. Remember that the certificates must be installed on all machines that need to run the robot.

INDEX

19

Upgrading from Earlier Versions

This chapter contains useful information if you are upgrading from earlier versions of Kapow Mashup Server.

Upgrading Clipping Robots and Portlets

A new clipping functionality was introduced in Kapow Mashup Server 6.0. This replaced the clipping functionality available in earlier versions of Kapow Mashup Server. The clipping functionality from the earlier versions is still available, and Kapow Mashup Server 6.4 is fully backwards compatible with clipping robots created using earlier versions. Clipping portlets generated by versions of Kapow Mashup Server earlier than Kapow Mashup Server 5.5 must be regenerated in RoboMaker 6.4 in order to work with RoboServer 6.4. Clipping portlets created using Kapow Mashup Server 5.5 need not be regenerated. To regenerate a portlet, load the clipping robot in RoboMaker 6.4, and in the Tools menu, select the appropriate clipping wizard.

20

INSTALLATION GUIDE

Index
B
bug reporting, 17

L
license changing information, 17 Linux installing on, 6 running RoboServer as a service, 17

C
certificates, 17 clipping portlets upgrading, 19 clipping robots upgrading, 19

P
proxy server, 15

D
databases character encoding, 12 configuring connections, 10 DB2, 13 drivers, 8, 13, 14 Microsoft SQL Server, 13 object databases, 10 Oracle, 12 PointBase, 14 RoboManager databases, 10, 11 downloading RoboSuite, 6, 7

R
RoboServer running as a service, 17 RoboSuite Settings, 9 robot project default, 8 setting the current, 10

S
silent installation, 7

W
web server, 16 admin security, 16 clustering, 16 Windows installing on, 6 running RoboServer as a service, 17

F
folders in RoboSuite, 7

H
headless installation, 7