Installation

Installation on Windows

Click the Windows download link on the Product Downloads page of the Customer Portal.

You will be provided with an installation package for Hub as a standard Windows MSI installer.

If prompted, click Save File and open the file once downloaded.

The Tasktop Setup Wizard will guide you through the installation process.

 Note: If you decide to change the location of the ProgramData directory, do not include spaces in the new directory name. If the directory includes spaces, Hub's UI will not be accessible.

After installing Hub, open the Start menu and click Start Tasktop to start both Hub and User Management services.

To stop both Hub and User Management services, click Stop Tasktop.

 Note: The Hub application is available via HTTPS on port 8443. A default SSL certificate is provided for testing purposes, however this SSL certificate is insecure. Before using in a production environment, the provided SSL certificate must be replaced. Please see details in the SSL Certificate Installation section below.

 Please follow the steps in the Getting Started section when starting Hub for the first time.

Powershell

Hub supports Windows environments that require PowerShell scripts to be signed, but Tasktop must be added to the Trusted Publishers store to run on such environments. To do this, see the steps below.

1. Install the latest version of Hub on the machine.
2. Log in as the user that will be used to run Hub.
3. Run PowerShell as administrator and navigate to C:\Program` Files\Tasktop\container\bin\setenv.ps1 
4. Type 'A' and press enter.

Alternatively, PowerShell commands can be used to add Tasktop to the Trusted Publishers store for the entire machine. 

Note that the following commands can be run by any user once Hub is installed and must be entered into a PowerShell terminal and not run as a PowerShell script.

$Cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2
$Cert.Import((((Get-AuthenticodeSignature "C:\Program Files\Tasktop\container\bin\setenv.ps1").SignerCertificate).Export([System.Security.Cryptography.X509Certificates.X509ContentType]::Cert)))
$store = Get-Item "cert:\LocalMachine\TrustedPublisher"
$store.Open([System.Security.Cryptography.X509Certificates.OpenFlags]"ReadWrite")
$store.Add($Cert)
$store.Close()

Installation on Linux

For Direct Customers

Click the Linux download link on the Product Downloads page of the Customer Portal.

You will be provided with an installation package for Hub as a .tar.gz archive.

To extract this archive to your desired location, copy the archive to the correct location on your Linux system.

You must choose a location with no spaces in its path and use the following command to extract:

$ tar -xzvf tasktop-linux-x64-<version>.tar.gz

After extracting, run the start-tasktop.sh script from the installation directory (see note on permissions below) to start Hub and User Management services.

To stop Hub and User Management services, use the stop-tasktop.sh script in the same folder.

 Please follow the steps in the Getting Started section when starting Hub for the first time.

For OEM Customers

You will be provided with a .bin installation package for Hub. 

To execute the file, run these commands:

chmod +x tasktop-linux-x64.bin

./tasktop-linux-x64.bin

After approving the End User License Agreement, the file will automatically unzip, allowing you to run Hub.

Run the start-tasktop.sh script from the installation directory (see note on permissions below) to start Hub and Keycloak User Management services.

To stop Hub and User Management services, use the stop-tasktop.sh script in the same folder.

 The Hub application is available via HTTPS on port 8443. A default SSL certificate is provided for testing purposes, however this SSL certificate is insecure. Before using in a production environment, the provided SSL certificate must be replaced. Please see details in the SSL Certificate Installation section below.

 Please follow the steps in the Getting Started section when starting Hub for the first time.

Note on Permissions

We recommend creating a dedicated user for running Hub. We do not recommend running Hub as root, as it may create files that cannot be accessed when running Hub as another user. Running an application on a Linux system as root may also interfere with your system's security.

For this reason, start-tasktop.sh will not start if it detects the current user is root.

If you would like to run Hub as root despite these risks, you can do so by deleting or commenting lines 3-7 of call-catalina.sh in the installation directory as shown below: 

!/bin/sh
#if [ "`id -u`" -eq "0" ]
#then
#    echo "Tasktop should not be run as root"
#    exit 1
#fi

Hub Service on Linux

There are several ways to configure a Hub Service that starts automatically on system startup. We recommend using a dedicated account for running Hub.

You can see the examples below for Systemd and SysVinit.

Hub Service with Systemd

1. Navigate to /etc/systemd/system
2. Create a file named tasktop.service

3. Paste the following into the file: 

   # Systemd unit file for tasktop
   [Unit]
   Description=Tasktop Hub
   After=syslog.target network.target
    
   [Service]
   Type=forking
    
   ExecStart=/path/to/tasktop/start-tasktop.sh
   ExecStop=/path/to/tasktop/stop-tasktop.sh
    
   User=user
   Group=group
    
   [Install]
   WantedBy=multi-user.target

   a. Change both instances of /path/to/tasktop to the full path to your Hub installation directory
   b. Change the User and Group variables to the username and group of the account you want to run the Hub service

4. Reload Systemd 

   $ systemctl daemon-reload

5. Enable the new Hub service to start on system startup 

   $ systemctl enable tasktop

 To manually start and stop the Hub Service, use the following commands: 

$ systemctl start tasktop
$ systemctl stop tasktop

Hub Service with SysVinit

1. Navigate to /etc/init.d
2. Create a file named tasktop

3. Paste the following into the file: 

   #!/bin/bash
   # description: Tasktop Start Stop Restart
   # processname: tasktop
   # chkconfig: 2345 20 80
   TASKTOP_HOME=/path/to/tasktop
   case $1 in
   start)
   sh $TASKTOP_HOME/start-tasktop.sh
   ;;
   stop)
   sh $TASKTOP_HOME/stop-tasktop.sh
   ;;
   restart)
   sh $TASKTOP_HOME/stop-tasktop.sh
   sh $TASKTOP_HOME/start-tasktop.sh
   ;;
   esac
   exit 0

   a. Change the TASKTOP_HOME variable to the full path to your Hub installation directory
   b. If you'd like, you can change the chkconfig run levels and start and stop priorities

4. Set the permissions of Hub to make it executable: 

   $ chmod 755 tasktop

5. Use the chkconfig utility to enable Hub start at system startup 

   $ chkconfig --add tasktop
   $ chkconfig --level 2345 tasktop on

   1. If you'd like, you can change the run levels in this command

 To manually start and stop the Hub Service, use the following commands: 

$ service tasktop start
$ service tasktop stop
$ service tasktop restart

SSL Certificate Installation 

The Hub application is available via HTTPS on port 8443. A default SSL certificate is provided for testing purposes and should be replaced after installation.

Replacing the default SSL certificate used by Hub involves the following:

1. Preparing a Java keystore file with all keys and certificates
   1. The Hub and Keycloak SSL configuration require a JKS format keystore.
      1. If your corporate CA provides a JKS keystore file, you can skip to the Configure Hub to use the keystore section and follow the steps using the JKS keystore file from your CA.
      2. If your CA requires you to provide a CSR and returns a certificate response to you, use the following steps to generate your own keystore file and CSR:
         1. Create a Java keystore file and generate a new key pair
         2. Generate a certificate request file
         3. Submit the file to a Certificate Authority (CA) and obtain the certificate and CA certificate trust chain
         4. Import the certificates to the keystore file
2. Configuring Hub to use the keystore (i.e., new key and certificate)

The SSL certificate should contain DNS names where the Hub server is accessible. The user's browser will verify that the name in the address bar matches the names listed in the certificate.Certificate Authority may be your internal corporate service, or you may use a public CA (e.g., Comodo, Let’s Encrypt). If you are planning to use a certificate from a public CA, your Hub instance must have a publicly recognizable DNS name that is owned by your organization.

SSL-related instructions on this page are provided as a reference only. Your Certificate Authority will have more detailed instructions on creating and importing certificates. These instructions are based on the use of a GUI tool Portecle, which can be downloaded here.

Note that Hub does not provide support for this third-party tool beyond the instructions shown below.

 Tip: You can create the Java keystore file on any machine and move the file to the server running Hub software; there is no need to install Portecle on the server running Hub.

If you cannot use Portecle and need to utilize standard Java command line utility keytool, please refer to Tomcat documentation. Upon following the documentation, use JRE installed with Hub software in the Tasktop installation directory (default C:\Program Files\Tasktop). Tasktop’s server.xml file is located in Tasktop's data directory (default: C:\ProgramData\Tasktop, or the location where Tasktop is installed on Linux) under container/conf/server.xml.

Running Portecle for SSL certificate installation 

To run Portecle for SSL certificate installation, see the instructions below:

1. Download and unzip Portecle.
2. Open the command prompt.
   1. For Windows, navigate to C:\Program Files\Tasktop\jre\bin\
   2. For Linux, navigate to <tasktop-install>/jre/bin/
3. Run the following command (changing /path/to/portecle/ to the location where you unzipped Portecle):

   1. java -jar /path/to/portecle/portecle.jar

Prepare a Java keystore file with all the keys and certificates 

To replace Hub’s default SSL certificate using Portecle, follow the instructions below:

Tip: Details on accessing Portecle can be found in the section above.

1. Create a key pair and keystore:

1. Start Portecle and click New Keystore in the toolbar and select JKS as the keystore type. 

   1. 

2. Click Generate Key Pair in the toolbar. You can leave the default settings for 2118 bit RSA key, or choose different settings if required by your company’s security policy. 

   1. 

3. In the Generate Certificate pop-up, enter the Fully Qualified Domain Name (FQDN) of your Hub server in the Common Name (CN) field and enter other fields as needed.

   1. In the Subject Alternative DNS Name field, enter the alternative domain name of the server, if one exists. Your certificate should include all DNS names that your users may use to connect to Hub. For internal corporate CA you can also use “short” names (i.e., tasktop, in addition to tasktop.acme.corp). In CA, these additional DNS names are called Subject Alternative Names, or SAN. You can specify one SAN at this point, and can usually add more names later when submitting your request to the CA.

      1. 

4. Enter tomcat as alias. 

   1. 

5. Create a new password for the key pair.

   1. Tip: You will need this password later when configuring Tomcat.

   2. 

6. You will see your newly created key pair in the list.

   1. 

7. Click Save Keystore in the toolbar to save the newly created keystore file. Here, use the same password that you entered for the key pair earlier.

   1. 

2. To generate a certificate request file (also known as Certificate Signing Request or CSR), right click on the tasktop key and select Generate Certification Request and save it to a file.

   1. 

3. Submit your CSR to a CA to obtain a Certificate.

    Note: For some CAs you will need to provide the list of all DNS names for your Hub server separately as they will ignore the SAN values in the certificate request. See your CA's documentation for more information.

4. Import the certificates to the keystore file.

1. If your CA provided a separate file with the CA certificate or trust chain, import it by selecting Import Trusted Certificate in the toolbar. If your CA provided only one file in response to your CSR, skip to 4b.

2. Import the server certificate by right clicking on the tasktop key, selecting Import CA Reply and choosing the server certificate file received from the CA.

   1. 

3. To verify the certificate chain, click Tools and then click Keystore Report.

Configure Hub to use the keystore 

1. Place your keystore file in a protected location that will not be wiped on Hub upgrade. We suggest using Tasktop's data directory (default C:\ProgramData\Tasktop, or the home directory of the user that Hub service is running as on Linux).
2. Open the tasktop-hub.properties file and configure the following properties:
   1. server.ssl.key-store - Location where the keystore file exists
   2. server.ssl.key-store-password - Password of keystore file
   3. server.ssl.key-store-type - Type of keystore file (e.g., JKS, PKCS12)
3. Restart Hub Service

 To learn more about creating a tasktop-hub.properties file, please see the section below.

By default, the SSL configuration has been configured to disable known weak ciphers. As new security information becomes available, the list of enabled ciphers should be updated accordingly.

Configure Keycloak User Management to use and trust Tasktop's keystore

In Planview Tasktop Hub version 20.4, both Tomcat and Keycloak share the same properties in the tasktop-hub.properties file as they share the same keystore file. See more details above.

 To learn more about creating a tasktop-hub.properties file, please see the section below.

Port Configuration

By default, Hub utilizes the ports listed in the table below.

If any of those ports are already being utilized for other purposes, you will need to change them. To view a list of all ports being used on your system, you can use the netstat-a command. This will help you determine which available ports you would like to use for Hub.

Here is a summary of each port Hub utilizes and the location where you can change it if it is already being used:

Tasktop Hub Port 

The default port Hub uses is 8443 for HTTPS and 8080 for HTTP, which redirects to HTTPS. If you'd like to change these ports to ease access for your users, or to accommodate a proxy, follow these instructions:

1. Open the tasktop-hub.properties file and configure the following properties:
   1. server.port - The http or https port
   2. server.redirect.port - The port that, if accessed, redirects to server.port
2. After changing the port, the address used to access Hub (i.e., http://localhost:8080) will need to be updated with the new port number in place of '8080.'

Please refer to the official documentation for additional configuration options.

To learn more about creating a tasktop-hub.properties file, please see the section below.

User Management (Keycloak) Port 

The default port for User Management is 8081. If you'd like to change the port that User Management (Keycloak) utilizes, follow the instructions here. If your User Management (Keycloak) utilizes a port other than 8081, you can instruct Hub to access User Management (Keycloak) via the correct port by following the instructions below.

1. Open the tasktop-hub.properties file and configure the following properties:
   1. keycloak.http.port - Keycloak http port
   2. keycloak.https.port - Keycloak https port

To learn more about creating a tasktop-hub.properties file, please see the section below.

Getting Started 

Once installation is complete, you can begin using Hub by opening https://localhost:8443/ in any of our supported browsers. 

Before logging on to Hub, you must log into the User Administration Console in order to create your admin user(s). The User Administration Console can be accessed via the User Administration Console link at the bottom of the Hub login page. Please review the User Management section for detailed instructions on how to create a user, login, and manage your user accounts.

Once logged in, you will be prompted to set a Master Password, which will be used to encrypt your repository credentials.

You will also need to apply your license before configuring your integrations. You can learn how to apply your license here.

Externalized Configuration

Planview Tasktop Hub enables you to externalize configurations from Tomcat, Keycloak, and certain application properties in a single place. This allows you to use property files to override default values such as:

• Keycloak: ports (e.g., http, https), Keycloak database paths, java memory variables, and custom system properties
• Tomcat: ports (e.g., http https), keystores (e.g., files, passwords, types), java memory variables, and custom system properties
• Application Properties: Derby, Tasktop Hub, Liquibase, log4j, and keycloak host

To override default values through a properties file, you must provide the tasktop-hub.properties file in a directory that Hub can scan and read.

This can be done as follows:

1. Rename the file tasktop-hub.properties.default to tasktop-hub.properties.

   1. For Windows, this file can be found in the App Data Directory.
   2. For Linux, this file can be found in the root level of the .tar.gz package.
      1. Note: For Linux users, we recommend creating an environment variable named TASKTOP_HOME with its value pointing to an exclusive directory where the tasktop-hub.properties file will be placed.
2. Provide values to properties that need to be overridden.

   1. For example, if you'd like to change the Tomcat https port to port 9443, uncomment the property from #server.port=8443 to server.port=9443

Good to Know: 

• Only properties/lines uncommented within the <AppDataDirectory>/tasktop-hub.properties file will be applied, otherwise Hub will assume default values for commented properties.
• Only properties at <AppDataDirectory>/tasktop-hub.properties file will be used; the file <AppDataDirectory>/tasktop-hub.properties.default is just a template and will not work in Hub.
• Keycloak properties prefixed with jboss have been deprecated. It is recommended to replace the prefix with keycloak. For example, jboss.http.port should be changed to keycloak.http.port.

Upgrading

Upgrading on Windows

The tasktop-hub.properties file will not be replaced or deleted during the installation/upgrade process. For this reason, newer versions of Hub can retain settings automatically after upgrading.

Upgrading on Linux

Because the properties file is placed in the $TASKTOP_HOME directory, newer versions of Hub will automatically apply all configurations.

If the properties file is not placed in the $TASKTOP_HOME directory, it is necessary to copy the properties file from the old installation directory to the new installation directory.

Upgrading from a Version Earlier than 20.4

If you have made manual changes to Tomcat and/or Keycloak files, you have two options upon upgrading to 20.4:

...
server.port=9443
...

Properties

The tasktop-hub.properties file contains three main blocks:

• Keycloak Properties
• Tomcat Properties
• Tasktop Hub Properties

Keycloak

The properties listed in the table below are used only if Hub is using Keycloak as an Authentication Provider. 

Note: Starting in 23.2, Keycloak runs on the Quarkus framework instead of the Jboss application server. This change led to the deprecation or renaming of certain properties as noted in the table below.

Good to Know