Administration Guide: Custom installation package for Microsoft Windows

Contents

• • System Requirements
  • Installing actiTIME (General Instructions)
  • Installing actiTIME Under IIS
  • Upgrading actiTIME from a Previous Version
  • User Documentation
  • Database Backup Instructions: MS Access
  • Database Backup Instructions: MySQL
  • Uninstalling actiTIME

System Requirements

1. Java SDK

   actiTIME requires Java 2 SDK 1.4.2 or higher which may be obtained at http://java.sun.com/javase/downloads/index.jsp.

   The link above points to the latest release of JDK. To get a previous JDK release use the following links: J2SE 5.0 or J2SE 1.4.2.

2. Apache Tomcat Application Server

   actiTIME requires Tomcat 4.1.x or higher which may be obtained at http://tomcat.apache.org/index.html

   NOTE: It is strongly recommended to install Tomcat into a directory which name and path do not contain spaces.

3. MS Access

   If you want actiTIME to work with MS Access database, you will need Microsoft Data Access Objects(DAO) 3.0 or later installed.

   Microsoft DAO is installed as a part of MS Access 97 or higher as well as a part of Windows XP, Windows Vista, and Windows 7 operating systems. If you want to install actiTIME on other Windows operating systems which do not have MS Access 97 or higher installed, you can install Microsoft DAO as a part of Microsoft Jet 4.0 Database Engine as described at http://support.microsoft.com/kb/239114/
   Please choose the MS Access database only if the expected number of actiTIME users is less than ten (10). Otherwise, please consider using the MySQL database platform to avoid performance degradation and collisions when updating data.

4. MySQL

   If you want actiTIME to work with MySQL database it will need MySQL 4.1.17+, 5.0.x or 5.1.x installed (you can download MySQL installation package from http://www.mysql.com/downloads/index.html).

   Please note that this version of actiTIME was not tested for compatibility with MySQL 6.0. So it is not recommended to use it with the current version of actiTIME.

5. Version of Microsoft Windows

   actiTIME supports Microsoft Windows 2k, 2003, 2008, XP, Vista, and Windows 7.

Installing actiTIME (General Instructions)

1. Unzip installation package (for actiTIME Basic this file is named actiTIME21_windows.zip) into a local directory. Subdirectory 'actiTIME' will appear. Note that if you extract the archive into the '<tomcat home>\webapps' you will only need to restart Tomcat server. Otherwise you will have to configure Tomcat to make it able to run actiTIME in another directory.

2. Enter the 'actiTIME' directory.

3. If you want actiTIME to work with MS Access database one of the following scripts without parameters:

   • setup_access_vista.vbs if you are using Windows Vista OS.
   • setup_access_win7.vbs if you are using Windows 7 OS.
   • setup_access.vbs otherwise

   If you want actiTIME to work with MySQL database server you must create a MySQL user account with all privileges on the database that will be created during the subsequent steps of installation. The default name of this database is 'actiTIME'. You can choose any other name, but then you have to specify this name as a parameter for the installation script.

   Launch one of the following scripts:

   • setup_mysql_vista.vbs if you are using Windows Vista OS.
   • setup_mysql_win7.vbs if you are using Windows 7 OS.
   • setup_mysql.vbs otherwise

   Both these scripts have the same launch format:

   (script name).vbs [/mysqlhome <MYSQLHOME>]
                     [/username <USERNAME>] [/password <PASSWORD>]
                     [/host <HOST>] [/port <PORT>] [/dbname <DBNAME>]
   

   where

   <MYSQLHOME> - The path to the MySQL installation directory. If not specified, setup script will ask for it when running.

   Setup script will then search for MySQL executable file at the following location: <MYSQLHOME> + "/bin/mysql".

   <USERNAME> - the MySQL user name under which actiTIME will create and use the database. If not specified, setup script will ask for it when running.

   <PASSWORD> - the password of user <USERNAME>. If not specified, setup script will ask for it when running.

   <HOST> - host name of the the server where MySQL server runs. If not specified the local host is assumed. Required if actiTIME has to use a remote MySQL database.

   <PORT> - port on which MySQL server is running. If not specified the default MySQL port will be used.

   <DBNAME> - the name of the database to be created. If not specified 'actitime' will be used as the database name.

   NOTE: If the script finds the previous version of the actiTIME database then it will back up the database to the actiTIME.mysql4.sql.backup_[current date] file.

4. Make necessary activities to the Tomcat application server if you want to run actiTIME in non-default configuration (different port, virtual host etc.).

   1. If you want to configure actiTIME to work via secure connections (HTTPS) you can use Tomcat's facilities, but it will significantly decrease the system performace since Tomcat's HTTPS module is built on Java and requires considerable computational resources.

      It is better to use Tomcat together with Apache web server (http://httpd.apache.org/). In this case secure requests will be processed without serious loss of performance. Apache HTTP server will handle HTTPS requests, decrypt them and then transfer decrypted data forwards to Tomcat. To make it work this way see the Tomcat and Apache documentation.

   2. If you want to run Tomcat with "-security" option, you will need to add special permissions to $CATALINA_HOME/conf/catalina.policy file (or $CATALINA_HOME/conf/tomcat.policy depending on the Tomcat version). Set of permissions depends on Tomcat version and its configuration.

      Examples of lines to add for different server versions are listed below:

      Tomcat 4.1.x:

      grant codeBase "file:<PATH>/actitime/-" {
        // Access to Tomcat libraries
        permission java.io.FilePermission "${catalina.home}${file.separator}server${file.separator}lib${file.separator}-", "read";
        permission java.io.FilePermission "${catalina.home}${file.separator}common${file.separator}lib${file.separator}-", "read";
      
        // Database access permissions
        //   put permissions specific to the type of
        //   used database here (see below)
      
        // Access to system properties
        permission java.util.PropertyPermission "org.apache.coyote.USE_CUSTOM_STATUS_MSG_IN_HEADER", "read";
        permission java.util.PropertyPermission "catalina.home", "read";
        permission java.util.PropertyPermission "file.encoding", "read";
        permission java.util.PropertyPermission "java.runtime.version", "read";
      
        // Network and Runtime permissions
        permission java.lang.RuntimePermission "getClassLoader";
        permission java.lang.RuntimePermission "accessDeclaredMembers";
        permission java.lang.RuntimePermission "accessClassInPackage.sun.security.provider";
      
        //File permissions
        permission java.io.FilePermission "<PATH>${file.separator}actitime${file.separator}img ${file.separator}custom${file.separator}*", "read,delete,write";
      
        // Optional permissions that would increase actiTIME performance
        permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
        permission java.lang.RuntimePermission "accessClassInPackage.sun.util.logging.resources";
        permission java.lang.RuntimePermission "defineClassInPackage.org.apache.jasper.runtime";
        permission java.lang.RuntimePermission "defineClassInPackage.org.apache.coyote.http11";
        permission java.lang.RuntimePermission "defineClassInPackage.org.apache.coyote";
      };
      
      
      

      Tomcat 5.5.x:

      grant codeBase "file:<PATH>/actitime/-" {
        // Access to Tomcat logs (necessary to allow Tomcat to rotate its logs)
        permission java.io.FilePermission "${catalina.home}${file.separator}logs", "read";
        permission java.io.FilePermission "${catalina.home}${file.separator}logs${file.separator}-", "write";
      
        // Database access permissions
        //   put permissions specific to the type of
        //   used database here (see below)
      
        // Access to Tomcat libraries
        permission java.io.FilePermission "${catalina.home}${file.separator}server${file.separator}lib${file.separator}-", "read";
        permission java.io.FilePermission "${catalina.home}${file.separator}common${file.separator}lib${file.separator}-", "read";
      
        // Access to system properties
        permission java.util.PropertyPermission "org.apache.coyote.USE_CUSTOM_STATUS_MSG_IN_HEADER", "read";
        permission java.util.PropertyPermission "catalina.home", "read";
        permission java.util.PropertyPermission "file.encoding", "read";
        permission java.util.PropertyPermission "java.runtime.version", "read";
      
        // Network and Runtime permissions
        permission java.lang.RuntimePermission "getClassLoader";
        permission java.lang.RuntimePermission "accessDeclaredMembers";
        permission java.lang.RuntimePermission "accessClassInPackage.org.apache.jasper.compiler";
        permission java.lang.RuntimePermission "accessClassInPackage.sun.security.provider";
      
        //File permissions
        permission java.io.FilePermission "<PATH>${file.separator}actitime${file.separator}img ${file.separator}custom${file.separator}*", "read,delete,write";
      
        // Optional permissions that would increase actiTIME performance
        permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
        permission java.lang.RuntimePermission "defineClassInPackage.java.lang";
        permission java.lang.RuntimePermission "accessClassInPackage.sun.util.logging.resources";
        permission java.lang.RuntimePermission "defineClassInPackage.org.apache.jasper.runtime";
        permission java.lang.RuntimePermission "defineClassInPackage.java.util";
        permission java.lang.RuntimePermission "accessClassInPackage.org.apache.coyote";
      };
      
      

      You will also need to add the following permission to the existing block "file:${catalina.home}/bin/tomcat-juli.jar" in the
      $CATALINA_HOME/conf/catalina.policy

      permission java.io.FilePermission "<PATH>${file.separator}actitime${file.separator}WEB-INF${file.separator}classes${file.separator}logging.properties", "read";
      
      

      Tomcat 6.0.x:

      grant codeBase "file:<PATH>/actitime/-" {
        // Access to Tomcat libraries
        permission java.io.FilePermission "${catalina.home}${file.separator}lib${file.separator}-", "read";
      
        // Access to Tomcat logs (necessary to allow Tomcat to rotate its logs)
        permission java.io.FilePermission "${catalina.home}${file.separator}logs", "read";
        permission java.io.FilePermission "${catalina.home}${file.separator}logs${file.separator}-", "write";
      
        // Database access permissions
        //   put permissions specific to the type of
        //   used database here (see below)
      
        // Access to system properties
        permission java.util.PropertyPermission "org.apache.coyote.USE_CUSTOM_STATUS_MSG_IN_HEADER", "read";
        permission java.util.PropertyPermission "catalina.home", "read";
        permission java.util.PropertyPermission "file.encoding", "read";
        permission java.util.PropertyPermission "java.runtime.version", "read";
      
        // Network and Runtime permissions
        permission java.net.NetPermission "specifyStreamHandler";
        permission java.lang.RuntimePermission "getClassLoader";
        permission java.lang.RuntimePermission "accessDeclaredMembers";
        permission java.lang.RuntimePermission "accessClassInPackage.org.apache.catalina.core";
        permission java.lang.RuntimePermission "accessClassInPackage.org.apache.catalina.util";
        permission java.lang.RuntimePermission "accessClassInPackage.org.apache.catalina";
        permission java.lang.RuntimePermission "accessClassInPackage.javax.servlet";
        permission java.lang.RuntimePermission "accessClassInPackage.sun.util.logging.resources";
        permission java.lang.RuntimePermission "accessClassInPackage.org.apache.tomcat.util.buf";
        permission java.lang.RuntimePermission "accessClassInPackage.org.apache.coyote";
        permission java.lang.RuntimePermission "accessClassInPackage.sun.security.provider";
      
        //File permissions
        permission java.io.FilePermission "<PATH>${file.separator}actitime${file.separator}img ${file.separator}custom${file.separator}*","read,delete,write";
      
        // Optional permissions that would increase actiTIME performance
        permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
        permission java.lang.RuntimePermission "defineClassInPackage.org.apache.jasper.runtime";
        permission java.lang.RuntimePermission "accessClassInPackage.org.apache.catalina";
        permission java.lang.RuntimePermission "defineClassInPackage.java.lang";
        permission java.lang.RuntimePermission "defineClassInPackage.java.util";
      };
      
      

      where

      <PATH> - path to the actiTIME directory or '${catalina.home}/webapps' if actiTIME is installed to webapps directory.

      If you use MySQL database, then add the following permission to 1-st block of permissions:

      permission java.net.SocketPermission "<HOST>:<PORT>", "connect,resolve";
      

      where

      <HOST> - host name or IP of the the server where MySQL server runs.

      <PORT> - port on which MySQL server is running (MySQL uses port 3306 by default).

      If you use MS Access database, then add the following permission to 1-st block of permissions:

      permission java.lang.RuntimePermission "loadLibrary.<ACCESS_DRIVER_PATH>";
      

      where

      <ACCESS_DRIVER_PATH> - shall be replaced with the value of the 'IzmDllPath' parameter taken from the
      '${catalina.home}/webapps/actitime/WEB-INF/classes/com/actimind/actitime/AT.properties' file.

5. Restart Tomcat.

   Now you can access actiTIME via web browser http://<server name>:8080/actiTIME if Tomcat is configured by default and actiTIME is installed into the '<tomcat home>\webapps' directory).

   Login as user 'admin' with password 'manager' to configure system users.

Installing actiTIME Under IIS

Normally IIS can not execute Java Servlets and Java Server Pages (JSPs) actiTIME is based on. However, it's possible to configure IIS so that it redirects HTTP requests to configured URLs to Tomcat Web server. This way IIS can serve clients of a Java-based web application.

To enable this interoperability between IIS and Tomcat Web Server, an additional component - 'JK ISAPI Redirector plug-in for IIS' should be installed on the same machine with IIS. Then IIS and Tomcat Web Server should be configured to work through this component.

This document contains step-by-step instructions on how to install JK ISAPI Redirector plug-in for IIS and configure IIS and Tomcat Web server properly. IIS and Tomcat Web Server should be installed before performing the steps below.

Step 1. Installing actiTIME under Apache Tomcat Web Server

The first step is the usual installation of actiTIME under Apache Tomcat Web Server. This procedure is described above.

Step 2. Configuring Tomcat Web Server

Go to the "[Tomcat Installation Directory]\conf\" and check that the following XML element exists and is not commented in the server.xml file:

The above example configures Tomcat to listen for HTTP requests redirected from IIS on port 8009. If this port is already in use on the machine where actiTIME is being installed, it can be changed.

Step 3. Downloading and Configuring JK ISAPI Redirector plug-in for IIS

You can download the ISAPI Redirector plug-in installer from the following location:

http://archive.apache.org/dist/tomcat/tomcat-connectors/jk/binaries/win32/
jk-1.2.15/isapi_redirect.msi

Run the installer by executing the downloaded file and follow the installation wizard steps. By default the files are installed into the "C:\Program Files\Apache Software Foundation\Jakarta Isapi Redirector" directory (hereafter referred to as [JK Redirector Dir]).

You will need to modify two files in the "[JK Redirector Dir]/conf" folder:

• uriworkermap.properties - tells IIS what requests to redirect to Tomcat
• workers.properties.minimal - tells IIS where (IP address and port) Tomcat is running.

The following modifications should be performed:

uriworkermap.properties

1. comment out all the mappings (by adding the '#' character at the beginning of each line) except '/jkmanager=jkstatus'

2. add the following mapping "/actitime/*=wlb"

Now the file should look like this:

workers.properties.minimal

In this file you need to modify the 'worker.ajp13w.host' property. This property should be set to the host name or the IP address of the machine where Tomcat (with actiTIME) is running. If Tomcat is running on the same machine as IIS, you can leave this property set to localhost. If you have specified host name other than localhost, please make sure the IIS machine can correctly resolve it to the appropriate IP address.

Also, if you have modified the port for the Tomcat AJP Connector on step 2, you will need to modify the 'worker.ajp13w.port' property as well.

You will find the example of the file contents below for the situation when Tomcat and IIS servers are running on the same machine, and the default port (8009) is used for AJP connections:

4. Configuring IIS

1. Open your Windows Control Panel

2. Open the Administrative Tools

3. Open the Internet Information Services Manager.

   You should see a window similar to the one below (note: The 'jakarta' virtual directory under the "Default Web Site" folder was created by the isapi_redirect.msi installer):

   

4. Create a virtual directory for actiTIME in IIS.

   1. Right-click on the default Web site and select "Virtual Directory" from the "New" menu.

      

   2. Press Next and set the alias value to the context name (without slashes) that was set for actiTIME in Tomcat. In our example this context name is 'actitime':

      

   3. On the next screen browse to the directory containing your 'isapi_redirect.dll' file (in our case it is located in the '[JK Redirector Dir]\bin' folder) and press Next.

      

   4. Make sure that the following permissions are set: read, run, and execute.

      

   5. Continue through the Virtual Directory Wizard until you reach the end and then press Finish.

5. Add the ISAPI Redirector to the default Web site: right-click on the default Web site and select the Properties item.

   

6. In the opened window select the 'ISAPI Filters' tab.

   If you see the "jakarta" filter created, you can press Ok and skip steps 7 and 8. Otherwise, press Add and proceed with the next steps.

7. Enter a filter name and browse to the location of the 'isapi_redirect.dll' file. The following screen-shot shows the values that should be entered:

   

8. Press OK in the 'Add/Edit Filter Propertie' dialog and OK button in the 'Default Web Site Properties' window (after that you are back to the Internet Information Services dialog).

9. Right click on the 'Web Service Extension' Folder and select 'Add a new Web service extension:' item:

   

10. Enter the following line into the 'Extension name' field in the opened window: Jakarta Isapi Redirector.

11. Press 'Add :' near the 'Required files' field and browse to the 'isapi_redirect.dll' file

    

12. Press OK until you are back to the 'Web Service Extention' folder.

13. Select the "Jakarta Isapi Redirector" on the right panel and press Allow:

    

14. Right click on the 'Local computer' folder (on the left panel) and select 'Save Configuration to Disk' from the 'All Tasks' menu:

    

15. The IIS configuration is complete now. Restart IIS to put the changes into effect.

16. After IIS is restarted, you can try to login into actiTIME.
    (the actiTIME URL should look like this: http://my.iis.server/actitime/).

Upgrading actiTIME from a Previous Version

1. Stop Tomcat server.

2. Unzip the installation package (for actiTIME Basic this file is named actiTIME20_windows.zip) to the parent directory of the 'actiTIME' directory (directory where actiTIME is installed). This will overwrite files of existing actiTIME installation with their new versions.

3. Enter the 'actiTIME' directory.

4. If current installation works with MS Access database launch one of the following scripts without parameters:

   • setup_access_vista.vbs if you are using Windows Vista OS.
   • setup_access_win7.vbs if you are using Windows 7 OS.
   • setup_access.vbs otherwise

   If current installation works with MySQL database server launch one of the following scripts:

   • setup_mysql_vista.vbs if you are using Windows Vista OS.
   • setup_mysql_win7.vbs if you are using Windows 7 OS.
   • setup_mysql.vbs otherwise

   Both these scripts have the same launch format:

   (script name).vbs [/mysqlhome <MYSQLHOME>]
   

   where

   <MYSQLHOME> - The path to the MySQL installation directory. If not specified, setup script will ask for it when running.

   Setup script will then search for MySQL executable file at the following location: <MYSQLHOME> + "/bin/mysql".

   Prior to updating database structure setup script backups database and saves data in a file in the 'actiTIME' directory.

   • For MySQL file name is
     actiTIME.mysql4.sql.backup_<YYYYMMDDhhmmss>

   • For MS Access file name is
     actiTIME.access97.mdb.backup_<YYYYMMDDhhmmss>.

   Where

   <YYYYMMDDhhmmss> is date and time when script was run.

5. Delete all files from the Tomcat cache directory
   <tomcat>\work\<Engine Name>\<Host Name>\actiTIME\

   Where

   <tomcat> is the directory where Tomcat is installed.

   <Engine Name> - name of the Tomcat engine configured for your installation. Usually is 'Standalone' or 'Catalina'.

   <Host Name> - name of the virtual host configured for your Tomcat installation.

6. Start Tomcat server.

User Documentation

After actiTIME installation is complete, the full HTML user documentation will be available in the actiTIME interface in the 'Help & Support' menu.

Database Backup Instructions: actiTIME with MS Access Database

Backup procedure:

1. Stop actiTIME

2. Go to the '<actiTIME installation directory>' folder and make a backup copy of the 'actitime.access97.mdb' file

Restore procedure:

1. Stop actiTIME

2. Go to the '<actiTIME installation directory>' folder and replace the file 'actitime.access97.mdb' with its backup copy

Database Backup Instructions: actiTIME with MySQL Database

Backup procedure:

1. Open CMD

2. Find the folder where MySQL is installed and go to the 'bin' folder.

3. Run the following command:

   mysqldump -u <username> -p<password> [-h <host>] [-P <port>] --protocol=tcp <dbname> > actitime_data.sql
   
   

   where

   square brackets [] indicate that the enclosed parameter is optional. Square brackets themselves must not be entered.

   <username> is the name of the user who has all the necessary rights to administer the database (you can also use 'root' for it).

   <password> is the password of this user (please note that there should be NO space between '-p' and 'password')

   <host> is the host name of the the server where MySQL server runs. If not specified the local host is assumed.

   <port> is the port used by MySQL. If not specified the default MySQL port will be used.

   <dbname> is the name of the MySQL database used by actiTIME. If you did not specify a custom database name when installing actiTIME, specify 'actitime' as the database name.

   Executing this command you will create a dump of your database and save it in the file 'actitime_data.sql'.

Restore procedure:

1. Open CMD

2. Find the folder where MySQL is installed and go to the 'bin' folder.

3. Run the following command:

   mysqladmin -f -u <username> -p<password> -h <host> -P <port> --protocol=tcp drop <dbname>
   
   

   After this command the current data will be dropped.

   mysqladmin -f -u <username> -p<password> [-h <host>] [-P <port>] --protocol=tcp create <dbname>
   
   mysql -u <username> -p<password> [-h <host>] [-P <port>] --protocol=tcp <dbname> < actitime_data.sql
   
   

   where

   square brackets [] indicate that the enclosed parameter is optional. Square brackets themselves must not be entered.

   <username> is the name of the user who has all the necessary rights to administer the database (you can also use 'root' for it).

   <password> is the password of this user (please note that there should be NO space between '-p' and 'password')

   <host> is the host name of the the server where MySQL server runs. If not specified the local host is assumed.

   <port> is the port used by MySQL. If not specified the default MySQL port will be used.

   <dbname> is the name of the MySQL database used by actiTIME. If you did not specify a custom database name when installing actiTIME, specify 'actitime' as the database name.

Uninstalling actiTIME

1. Stop the Tomcat server.

2. Enter the 'actiTIME' directory.

3. If you were using actiTIME with MS Access database, backup your database file (actiTIME.access97.mdb) if necessary, and then launch one of the following cleanup scripts without parameters:

   • cleanup_access_vista.vbs if you are using Windows Vista OS.
   • cleanup_access_win7.vbs if you are using Windows 7 OS.
   • cleanup_access.vbs otherwise

   If you were using actiTIME with MySQL database and you would like to remove actiTIME database with all the data, launch launch one of the following scripts:

   • cleanup_mysql_vista.vbs if you are using Windows Vista OS.
   • cleanup_mysql_win7.vbs if you are using Windows 7 OS.
   • cleanup_mysql.vbs otherwise

   Both these scripts have the same launch format:

   (script name).vbs [/mysqlhome <MYSQLHOME>]
   

   where

   <MYSQLHOME> - The path to the MySQL installation directory. If not specified, cleanup script will ask for it when running.

   Cleanup script will then search for MySQL executable file at the following location: <MYSQLHOME> + "/bin/mysql".

4. Delete the 'actiTIME' directory and all its subdirectories.