How to Install Issuetrak Using the Issuetrak Deployment Utility (IDU)

Introduction

This article is intended to assist the Issuetrak administrator with using the Issuetrak Deployment Utility (IDU) to deploy a new production installation of Issuetrak. If you're looking for instructions on how to deploy a test Issuetrak instance, please use the guide here instead.

The IDU provides granular control over the deployment of our product. If you want maximum involvement in the deployment of Issuetrak, and you're comfortable with using PowerShell and hand-editing configuration files, then the IDU is for you.

If you just want to install or upgrade Issuetrak without any special requirements, then we recommend that you use the Issuetrak Deployment Manager (IDM), which provides a graphical interface and a wizard to help you deploy our product, while retaining a fair degree of control over how the site is installed. You can get to the IDM installation guide here.

This installation guide is intended to be used after reading the information provided in the following articles:

Introduction to the IDU
IDU Verb Documentation
Working with the JSON

The reader would be well-advised to read the supporting documentation listed above before proceeding with the steps outlined here.


Identifying Requirements

Please ensure that your environment meets Issuetrak's system requirements. It may be necessary to add roles and features that aren't currently installed on the Web or SQL servers. Additional configuration beyond roles and features may also be required.

Beyond the Issuetrak product‘s requirements, you may also need to evaluate the requirements of your environment and listen to the feedback of your organization’s stakeholders.

Here are some things to consider:

  • What will you name the initial organization in Issuetrak?
  • What password should be set for the default ‘admin’ user within Issuetrak?
  • Do you have your Site ID handy? (You can contact Issuetrak Support to get this information.)
  • Will you be using Windows or SQL authentication to install Issuetrak?
  • Will your site run using Integrated Security or SQL users?
  • Will the API or API v2 need to be installed?
    • If so, make sure to include the relevant API/API v2 objects in your JSON.
    • If not, you should omit the API/API v2 objects from the JSON.

You will need the information above when you go to customize your JSON later in this article.

Building the JSON

You will be working with what you learned in Working with the JSON. We will need to change one of the JSON files provided with the distribution.

  1. Open the Distribution folder.
  2. Make a copy of the file deployment-example-complete.json and rename it to your preference.
  3. Open your copy of the JSON with a text editor.

Consider using an advanced text editor such as Notepad++ to make it easier to view the file structure and identify syntax errors.

  1. Populate the JSON values with ones that will suit your environment and needs. Remember to escape special characters such as backslashes (by just adding another backslash) wherever they appear.
  2. When you are confident that you have the JSON filled out appropriately, verify the configuration:
.\issuetrak.deployment.utility verifyconfiguration -c filename.json

The verifyconfiguration verb will only verify that it's parsing a valid JSON and that all necessary values are filled. It will not determine if the information is correct or realistic.

Getting the Issuetrak Distribution

Download the latest Issuetrak distribution.

You will be prompted to enter your credentials to access our Support site in order to download the distribution.

Once you've downloaded the distribution, place it on the Web server and extract it. If it is necessary to transfer the distribution to another server after downloading it, be sure to unblock the zip file prior to extracting it.

Deploying Issuetrak

Open the verb documentation to the Deploy section if you haven't already. Read through the possible parameters and make a decision on which of them you will use in the deployment of your site.

Triple-check the information you entered, and validate that the information in the JSON is entered correctly. When you move to deploy this JSON as a new Issuetrak site, the IDU will do its best to carry out the deployment. Incorrect information here can lead to corruption of existing sites, hard-to-correct misspellings, overwritten databases, and/or overwritten data.

If you are ready to deploy your new Issuetrak site, follow the steps below:

  1. Open PowerShell with administrative privileges and change directories to the location of the extracted distribution.
  1. Run the following command, substituting in your own JSON filename, and add any further parameters you need:
.\issuetrak.deployment.utility deploy -c config.json

The IDU will ask you whether you accept the terms of service at https://helpcenter.issuetrak.com/home/2360-issuetrak-premise-software-license-agreement. If you accept the terms, the IDU will begin to carry out the deployment. IDU output in the PowerShell window will indicate what it's doing and whether it succeeded at each step.

Failed Deployment?

Get as much context from the PowerShell window as you can. Something as simple as a misspelled server name can cause the deployment to fail. If the root cause is unclear, proceed with the steps below:

  1. Open Explorer and navigate to your Issuetrak distribution folder.
  2. Open the Logs folder.
  3. Open the latest timestamped log file.
  4. Read the log and try to determine where the deployment failed.
  5. Change the JSON or your IDU command accordingly, then re-run the deployment.
  6. If the deployment fails again, determine if it's the same problem or a new one, and re-apply the steps above as needed.

If the steps above failed, Issuetrak Support will be happy to troubleshoot or assist you with your deployment. You can contact Support at 888-789-8725 (US & Canada), +1 757-213-1351 (International), support@issuetrak.com or https://support.issuetrak.com/.

Successful Deployment

Congratulations on your first successful deployment of Issuetrak! There's some post-deployment configuration work that should be done to get your site towards a useful state.